

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    
    <title>FatGHoL programming API &mdash; FatGHoL v5.4 documentation</title>
    <link rel="stylesheet" href="_static/default.css" type="text/css" />
    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    '',
        VERSION:     '5.4',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  true
      };
    </script>
    <script type="text/javascript" src="_static/jquery.js"></script>
    <script type="text/javascript" src="_static/underscore.js"></script>
    <script type="text/javascript" src="_static/doctools.js"></script>
    <link rel="top" title="FatGHoL v5.4 documentation" href="index.html" />
    <link rel="prev" title="Using FatGHoL" href="using.html" />
 
<script type="text/javascript">
  var _gaq = _gaq || [];
  _gaq.push(['_setAccount', 'UA-23673826-1']);
  _gaq.push(['_trackPageview']);
</script>

  </head>
  <body>
    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             accesskey="I">index</a></li>
        <li class="right" >
          <a href="py-modindex.html" title="Python Module Index"
             >modules</a> |</li>
        <li class="right" >
          <a href="using.html" title="Using FatGHoL"
             accesskey="P">previous</a> |</li>
        <li><a href="index.html">FatGHoL v5.4 documentation</a> &raquo;</li> 
      </ul>
    </div>  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body">
            
  <div class="section" id="fatghol-programming-api">
<h1>FatGHoL programming API<a class="headerlink" href="#fatghol-programming-api" title="Permalink to this headline">¶</a></h1>
<p>This is the documentation of the functions and classes available in
the <tt class="docutils literal"><span class="pre">fatghol</span></tt> Python module, for use in your own programs.</p>
<div class="section" id="fatgraph-related-modules">
<h2>Fatgraph-related modules<a class="headerlink" href="#fatgraph-related-modules" title="Permalink to this headline">¶</a></h2>
<p>This is the core of FatGHOL: the Python modules that implement an
interface for generating fatgraphs and computing their homology
complex.</p>
<div class="section" id="module-fatghol.rg">
<span id="fatghol-rg"></span><h3><cite>fatghol.rg</cite><a class="headerlink" href="#module-fatghol.rg" title="Permalink to this headline">¶</a></h3>
<p>Classes and functions to deal with fatgraphs.</p>
<dl class="class">
<dt id="fatghol.rg.BoundaryCycle">
<em class="property">class </em><tt class="descclassname">fatghol.rg.</tt><tt class="descname">BoundaryCycle</tt><a class="reference internal" href="_modules/fatghol/rg.html#BoundaryCycle"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.rg.BoundaryCycle" title="Permalink to this definition">¶</a></dt>
<dd><p>A boundary cycle of a Fatgraph.</p>
<p>Boundary cycles are a cyclic sequence of &#8216;corners&#8217;: a corner
consists of a vertex <cite>v</cite> and (an unordered pair of) two
consecutive indices (in the cyclic order at <cite>v</cite>, so, either
<cite>j == i+1</cite> or <cite>i</cite> and <cite>j</cite> are the starting and ending indices).</p>
<p>Two boundary cycles are equal if they comprise the same
corners.</p>
<p>A <cite>BoundaryCycle</cite> instance is constructed from a sequence of
triples <cite>(v, i, j)</cite>, where <cite>i</cite> and <cite>j</cite> are consecutive (in the
cyclic order sense) indices at a vertex <cite>v</cite>.  (Although no check
is performed in the constructor code.)</p>
</dd></dl>

<dl class="class">
<dt id="fatghol.rg.Edge">
<em class="property">class </em><tt class="descclassname">fatghol.rg.</tt><tt class="descname">Edge</tt><big>(</big><em>va1</em>, <em>va2</em><big>)</big><a class="reference internal" href="_modules/fatghol/rg.html#Edge"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.rg.Edge" title="Permalink to this definition">¶</a></dt>
<dd><p>An edge of a fatgraph.</p>
<p>An edge is represented by its two endpoints; each endpoint has the form
<cite>(v_idx, a_idx)</cite>, where:</p>
<blockquote>
<div><ul class="simple">
<li><cite>v_idx</cite> is the index of the endpoint vertex (within the fatgraph), and</li>
<li><cite>a_idx</cite> is the index at which this edge appears within the vertex <cite>v_idx</cite>.</li>
</ul>
</div></blockquote>
<p>It is guaranteed that endpoints are stored in increasing vertex
index order:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">x</span> <span class="o">=</span> <span class="n">Edge</span><span class="p">((</span><span class="mi">3</span><span class="p">,</span> <span class="mi">0</span><span class="p">),</span> <span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">))</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">x</span><span class="o">.</span><span class="n">endpoints</span>
<span class="go">((1, 2), (3, 0))</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">x</span><span class="o">.</span><span class="n">endpoints</span><span class="p">[</span><span class="mi">0</span><span class="p">][</span><span class="mi">0</span><span class="p">]</span> <span class="o">&lt;</span> <span class="n">x</span><span class="o">.</span><span class="n">endpoints</span><span class="p">[</span><span class="mi">1</span><span class="p">][</span><span class="mi">0</span><span class="p">]</span>
<span class="go">True</span>
</pre></div>
</div>
<p><cite>Edge</cite> objects bear no reference to a particular <cite>Fatgraph</cite>
instance, to allow sharing the same edge instance among
<a href="#id1"><span class="problematic" id="id2">`</span></a>Fatgraph`s that are created by contraction or other geometrical
operations.</p>
<dl class="method">
<dt id="fatghol.rg.Edge.is_loop">
<tt class="descname">is_loop</tt><big>(</big><big>)</big><a class="reference internal" href="_modules/fatghol/rg.html#Edge.is_loop"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.rg.Edge.is_loop" title="Permalink to this definition">¶</a></dt>
<dd><p>Return <cite>True</cite> if this <cite>Edge</cite> instance represents looping edge.</p>
<p>Examples:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">Edge</span><span class="p">((</span><span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">),</span> <span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">2</span><span class="p">))</span><span class="o">.</span><span class="n">is_loop</span><span class="p">()</span>
<span class="go">True</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">Edge</span><span class="p">((</span><span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">),</span> <span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">3</span><span class="p">))</span><span class="o">.</span><span class="n">is_loop</span><span class="p">()</span>
<span class="go">False</span>
</pre></div>
</div>
</dd></dl>

<dl class="method">
<dt id="fatghol.rg.Edge.meets">
<tt class="descname">meets</tt><big>(</big><em>v</em><big>)</big><a class="reference internal" href="_modules/fatghol/rg.html#Edge.meets"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.rg.Edge.meets" title="Permalink to this definition">¶</a></dt>
<dd><p>Return <cite>True</cite> if vertex <cite>v</cite> is one of the endpoints.</p>
<p>Example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">x</span> <span class="o">=</span> <span class="n">Edge</span><span class="p">((</span><span class="mi">3</span><span class="p">,</span> <span class="mi">1</span><span class="p">),</span> <span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">))</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">x</span><span class="o">.</span><span class="n">meets</span><span class="p">(</span><span class="mi">3</span><span class="p">)</span>
<span class="go">True</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">x</span><span class="o">.</span><span class="n">meets</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>
<span class="go">True</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">x</span><span class="o">.</span><span class="n">meets</span><span class="p">(</span><span class="mi">0</span><span class="p">)</span>
<span class="go">False          </span>
</pre></div>
</div>
</dd></dl>

<dl class="method">
<dt id="fatghol.rg.Edge.other_end">
<tt class="descname">other_end</tt><big>(</big><em>v</em>, <em>a</em><big>)</big><a class="reference internal" href="_modules/fatghol/rg.html#Edge.other_end"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.rg.Edge.other_end" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the endpoint opposed to <cite>(v, a)</cite>.</p>
<p>Example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">l</span> <span class="o">=</span> <span class="n">Edge</span><span class="p">((</span><span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">),</span> <span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">3</span><span class="p">))</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">l</span><span class="o">.</span><span class="n">other_end</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">)</span>
<span class="go">(1, 3)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">l</span><span class="o">.</span><span class="n">other_end</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span><span class="mi">3</span><span class="p">)</span>
<span class="go">(0, 1)</span>
</pre></div>
</div>
</dd></dl>

</dd></dl>

<dl class="class">
<dt id="fatghol.rg.EqualIfIsomorphic">
<em class="property">class </em><tt class="descclassname">fatghol.rg.</tt><tt class="descname">EqualIfIsomorphic</tt><big>(</big><em>invariants</em><big>)</big><a class="reference internal" href="_modules/fatghol/rg.html#EqualIfIsomorphic"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.rg.EqualIfIsomorphic" title="Permalink to this definition">¶</a></dt>
<dd><p>Instances of this class will compare equal if there is an
isomorphism mapping one to the other.</p>
</dd></dl>

<dl class="class">
<dt id="fatghol.rg.Fatgraph">
<em class="property">class </em><tt class="descclassname">fatghol.rg.</tt><tt class="descname">Fatgraph</tt><big>(</big><em>g_or_vs</em>, <em>**kwargs</em><big>)</big><a class="reference internal" href="_modules/fatghol/rg.html#Fatgraph"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.rg.Fatgraph" title="Permalink to this definition">¶</a></dt>
<dd><p>A fully-decorated ribbon graph.</p>
<p>Several attributes of this object are computed at init time and
store characteristics of the fatgraph:</p>
<blockquote>
<div><dl class="docutils">
<dt><cite>.boundary_cycles</cite></dt>
<dd>List of the boundary components of this <cite>Fatgraph</cite> object.
Each boundary component is represented by the list of
(colored) edges.</dd>
<dt><cite>.genus</cite></dt>
<dd>The genus of the Riemann surface this fatgraph lies on.</dd>
<dt><cite>.num_boundary_cycles</cite></dt>
<dd>Number of boundary cycles of this <cite>Fatgraph</cite>.</dd>
<dt><cite>.num_edges</cite></dt>
<dd>The number of edges of this <cite>Fatgraph</cite> object.</dd>
<dt><cite>.num_vertices</cite></dt>
<dd>Number of vertices of this <cite>Fatgraph</cite> object.</dd>
<dt><cite>.vertices</cite></dt>
<dd>List of vertices of this <cite>Fatgraph</cite>; each one is an instance
of the <cite>Vertex</cite> class; see <cite>Fatgraph.__init__</cite> for examples.</dd>
</dl>
</div></blockquote>
<dl class="docutils">
<dt>Examples::</dt>
<dd><div class="first last highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">Fatgraph</span><span class="p">([</span><span class="n">Vertex</span><span class="p">([</span><span class="mi">2</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">0</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">2</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">0</span><span class="p">])])</span><span class="o">.</span><span class="n">num_boundary_cycles</span>
<span class="go">1</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">Fatgraph</span><span class="p">([</span><span class="n">Vertex</span><span class="p">([</span><span class="mi">2</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">0</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">2</span><span class="p">,</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">])])</span><span class="o">.</span><span class="n">num_boundary_cycles</span>
<span class="go">3</span>
</pre></div>
</div>
</dd>
</dl>
<p>Two <a href="#id3"><span class="problematic" id="id4">`</span></a>Fatgraph`s compare equal if they are isomorphic:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">Fatgraph</span><span class="p">([</span><span class="n">Vertex</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span><span class="mi">0</span><span class="p">,</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">])])</span> <span class="o">==</span> <span class="n">Fatgraph</span><span class="p">([</span><span class="n">Vertex</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">0</span><span class="p">,</span><span class="mi">0</span><span class="p">])])</span>
<span class="go">True</span>

<span class="gp">&gt;&gt;&gt; </span><span class="n">Fatgraph</span><span class="p">([</span><span class="n">Vertex</span><span class="p">([</span><span class="mi">2</span><span class="p">,</span><span class="mi">0</span><span class="p">,</span><span class="mi">0</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">2</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">1</span><span class="p">])])</span>             <span class="o">==</span> <span class="n">Fatgraph</span><span class="p">([</span><span class="n">Vertex</span><span class="p">([</span><span class="mi">2</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">0</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">0</span><span class="p">])])</span>
<span class="go">True</span>

<span class="gp">&gt;&gt;&gt; </span><span class="n">Fatgraph</span><span class="p">([</span><span class="n">Vertex</span><span class="p">([</span><span class="mi">2</span><span class="p">,</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">2</span><span class="p">,</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">])])</span>             <span class="o">==</span> <span class="n">Fatgraph</span><span class="p">([</span><span class="n">Vertex</span><span class="p">([</span><span class="mi">2</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">0</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">2</span><span class="p">,</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">])])</span>
<span class="go">False</span>

<span class="gp">&gt;&gt;&gt; </span><span class="n">Fatgraph</span><span class="p">([</span><span class="n">Vertex</span><span class="p">([</span><span class="mi">2</span><span class="p">,</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">2</span><span class="p">,</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">])])</span>             <span class="o">==</span> <span class="n">Fatgraph</span><span class="p">([</span><span class="n">Vertex</span><span class="p">([</span><span class="mi">2</span><span class="p">,</span><span class="mi">0</span><span class="p">,</span><span class="mi">0</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">2</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">1</span><span class="p">])])</span>
<span class="go">False</span>

<span class="gp">&gt;&gt;&gt; </span><span class="n">Fatgraph</span><span class="p">([</span><span class="n">Vertex</span><span class="p">([</span><span class="mi">2</span><span class="p">,</span><span class="mi">0</span><span class="p">,</span><span class="mi">0</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">2</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">1</span><span class="p">])])</span>             <span class="o">==</span> <span class="n">Fatgraph</span><span class="p">([</span><span class="n">Vertex</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">0</span><span class="p">,</span><span class="mi">0</span><span class="p">])])</span>
<span class="go">False</span>
</pre></div>
</div>
<dl class="method">
<dt id="fatghol.rg.Fatgraph.automorphisms">
<tt class="descname">automorphisms</tt><big>(</big><big>)</big><a class="reference internal" href="_modules/fatghol/rg.html#Fatgraph.automorphisms"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.rg.Fatgraph.automorphisms" title="Permalink to this definition">¶</a></dt>
<dd><p>Enumerate automorphisms of this <cite>Fatgraph</cite> object.</p>
<p>See <cite>.isomorphisms()</cite> for details of how a <cite>Fatgraph</cite>
isomorphism is represented.</p>
</dd></dl>

<dl class="method">
<dt id="fatghol.rg.Fatgraph.bridge">
<tt class="descname">bridge</tt><big>(</big><em>edge1</em>, <em>side1</em>, <em>edge2</em>, <em>side2</em><big>)</big><a class="reference internal" href="_modules/fatghol/rg.html#Fatgraph.bridge"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.rg.Fatgraph.bridge" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a new <cite>Fatgraph</cite>, formed by inserting trivalent
vertices in the middle of edges <cite>edge1</cite> and <cite>edge2</cite> and
connecting them with a new edge.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">g</span> <span class="o">=</span> <span class="n">Fatgraph</span><span class="p">([</span><span class="n">Vertex</span><span class="p">([</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">0</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">1</span><span class="p">])])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">g1</span> <span class="o">=</span> <span class="n">g</span><span class="o">.</span><span class="n">bridge</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">g1</span> <span class="ow">is</span> <span class="n">g</span>
<span class="go">False</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">g1</span> <span class="o">==</span> <span class="n">g</span>
<span class="go">False</span>
</pre></div>
</div>
<p>Arguments <cite>side1</cite> and <cite>side2</cite> control which side the new edge
is attached to (valid values are 0 or 1), i.e., which of the
two inequivalent cyclic orders the new trivalent vertices will
be given:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">g</span> <span class="o">=</span> <span class="n">Fatgraph</span><span class="p">([</span><span class="n">Vertex</span><span class="p">([</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">0</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">1</span><span class="p">])])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">g1</span> <span class="o">=</span> <span class="n">g</span><span class="o">.</span><span class="n">bridge</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">0</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">g2</span> <span class="o">=</span> <span class="n">g</span><span class="o">.</span><span class="n">bridge</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">0</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">g1</span> <span class="o">==</span> <span class="n">g2</span>
<span class="go">False</span>
</pre></div>
</div>
<p>In more detail: let 0,1,2 be the indices of the edges attached
to the new vertex in the middle of <cite>edge1</cite>, where 0,1 denote
the two halves of <cite>edge1</cite>.  If <cite>side1</cite> is <cite>0</cite>, then the new
trivalent vertex will have the cyclic order [0,1,2]; if
<cite>side1</cite> is <cite>1</cite>, then 0,1 are swapped and the new trivalent
vertex gets the cyclic order [1,0,2]:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">g1</span> <span class="o">==</span> <span class="n">Fatgraph</span><span class="p">([</span><span class="n">Vertex</span><span class="p">([</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">4</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">5</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">0</span><span class="p">,</span><span class="mi">4</span><span class="p">,</span><span class="mi">3</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span><span class="mi">5</span><span class="p">,</span><span class="mi">3</span><span class="p">])])</span>
<span class="go">True</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">g2</span> <span class="o">==</span> <span class="n">Fatgraph</span><span class="p">([</span><span class="n">Vertex</span><span class="p">([</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">4</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">5</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">4</span><span class="p">,</span><span class="mi">0</span><span class="p">,</span><span class="mi">3</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span><span class="mi">5</span><span class="p">,</span><span class="mi">3</span><span class="p">])])</span>
<span class="go">True</span>
</pre></div>
</div>
<p>It is worth noting that this procedure involves 5 edges in
total, 3 of which need new indices.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">g</span><span class="o">.</span><span class="n">num_edges</span>
<span class="go">3</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">g1</span><span class="o">.</span><span class="n">num_edges</span>
<span class="go">6</span>
</pre></div>
</div>
<p>This function is obviously symmetric: the pairs <cite>edge1, side1</cite>
and <cite>edge2, side2</cite> can be swapped and the result stays the
same:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">g3</span> <span class="o">=</span> <span class="n">g</span><span class="o">.</span><span class="n">bridge</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">g1</span> <span class="o">==</span> <span class="n">g3</span>
<span class="go">True</span>

<span class="gp">&gt;&gt;&gt; </span><span class="n">g4</span> <span class="o">=</span> <span class="n">g</span><span class="o">.</span><span class="n">bridge</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">g2</span> <span class="o">==</span> <span class="n">g4</span>
<span class="go">True</span>
</pre></div>
</div>
<p>Examples:</p>
<p>1) Bridging different sides of the same edge may yield
different results:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">g</span><span class="o">.</span><span class="n">bridge</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">0</span><span class="p">)</span>  <span class="o">==</span> <span class="n">Fatgraph</span><span class="p">([</span><span class="n">Vertex</span><span class="p">([</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">4</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">5</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">0</span><span class="p">,</span><span class="mi">4</span><span class="p">,</span><span class="mi">3</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span><span class="mi">5</span><span class="p">,</span><span class="mi">3</span><span class="p">])])</span>
<span class="go">True</span>

<span class="gp">&gt;&gt;&gt; </span><span class="n">g</span><span class="o">.</span><span class="n">bridge</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">0</span><span class="p">)</span> <span class="o">==</span> <span class="n">Fatgraph</span><span class="p">([</span><span class="n">Vertex</span><span class="p">([</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">4</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">5</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">4</span><span class="p">,</span><span class="mi">0</span><span class="p">,</span><span class="mi">3</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span><span class="mi">5</span><span class="p">,</span><span class="mi">3</span><span class="p">])])</span>
<span class="go">True</span>
</pre></div>
</div>
<ol class="arabic simple" start="2">
<li>One can connect an edge to itself on different sides:</li>
</ol>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">g</span><span class="o">.</span><span class="n">bridge</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">)</span> <span class="o">==</span> <span class="n">Fatgraph</span><span class="p">([</span><span class="n">Vertex</span><span class="p">([</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">5</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">1</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">0</span><span class="p">,</span><span class="mi">4</span><span class="p">,</span><span class="mi">3</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">5</span><span class="p">,</span><span class="mi">4</span><span class="p">,</span><span class="mi">3</span><span class="p">])])</span>
<span class="go">True</span>
</pre></div>
</div>
<ol class="arabic simple" start="3">
<li>And also with both ends on the same side:</li>
</ol>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">g</span><span class="o">.</span><span class="n">bridge</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">)</span> <span class="o">==</span> <span class="n">Fatgraph</span><span class="p">([</span><span class="n">Vertex</span><span class="p">([</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">5</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">1</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">0</span><span class="p">,</span><span class="mi">4</span><span class="p">,</span><span class="mi">3</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">4</span><span class="p">,</span><span class="mi">5</span><span class="p">,</span><span class="mi">3</span><span class="p">])])</span>
<span class="go">True</span>
</pre></div>
</div>
</dd></dl>

<dl class="method">
<dt id="fatghol.rg.Fatgraph.bridge2">
<tt class="descname">bridge2</tt><big>(</big><em>edge1</em>, <em>side1</em>, <em>other</em>, <em>edge2</em>, <em>side2</em><big>)</big><a class="reference internal" href="_modules/fatghol/rg.html#Fatgraph.bridge2"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.rg.Fatgraph.bridge2" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a new <cite>Fatgraph</cite>, formed by connecting the midpoints
of <cite>edge1</cite> on <cite>self</cite> and <cite>edge2</cite> on <cite>other</cite>.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">g1</span> <span class="o">=</span> <span class="n">Fatgraph</span><span class="p">([</span><span class="n">Vertex</span><span class="p">([</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">0</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">1</span><span class="p">])])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">g2</span> <span class="o">=</span> <span class="n">Fatgraph</span><span class="p">([</span><span class="n">Vertex</span><span class="p">([</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">])])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">g</span> <span class="o">=</span> <span class="n">Fatgraph</span><span class="o">.</span><span class="n">bridge2</span><span class="p">(</span><span class="n">g1</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="n">g2</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">g</span> <span class="ow">is</span> <span class="n">g1</span>
<span class="go">False</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">g</span> <span class="ow">is</span> <span class="n">g2</span>
<span class="go">False</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">g</span> <span class="o">==</span> <span class="n">Fatgraph</span><span class="p">([</span><span class="n">Vertex</span><span class="p">([</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">6</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">1</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">3</span><span class="p">,</span><span class="mi">4</span><span class="p">,</span><span class="mi">5</span><span class="p">,</span><span class="mi">3</span><span class="p">,</span><span class="mi">7</span><span class="p">,</span><span class="mi">5</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">0</span><span class="p">,</span><span class="mi">6</span><span class="p">,</span><span class="mi">8</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">4</span><span class="p">,</span><span class="mi">7</span><span class="p">,</span><span class="mi">8</span><span class="p">])])</span>
<span class="go">True</span>
</pre></div>
</div>
<p>New trivalent vertices are inserted in the middle of the
connected edges.  Arguments <cite>side1</cite> and <cite>side2</cite> control which
side the new edge is attached to (valid values are 0 or 1),
i.e., which of the two inequivalent cyclic orders the new
trivalent vertices will be given (see <cite>Fatgraph.bridge()</cite>).</p>
<p>It is worth noting that this procedure adds 3 edges and 2
vertices to the edge total of <cite>self</cite> and <cite>other</cite>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">g</span><span class="o">.</span><span class="n">num_edges</span> <span class="o">==</span> <span class="n">g1</span><span class="o">.</span><span class="n">num_edges</span> <span class="o">+</span> <span class="n">g2</span><span class="o">.</span><span class="n">num_edges</span> <span class="o">+</span> <span class="mi">3</span>
<span class="go">True</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">g</span><span class="o">.</span><span class="n">num_vertices</span> <span class="o">==</span> <span class="n">g1</span><span class="o">.</span><span class="n">num_vertices</span> <span class="o">+</span> <span class="n">g2</span><span class="o">.</span><span class="n">num_vertices</span> <span class="o">+</span> <span class="mi">2</span>
<span class="go">True</span>
</pre></div>
</div>
<p>This function is obviously symmetric: the triplets <cite>self, edge1, side1</cite>
and <cite>other, edge2, side2</cite> can be swapped and the result stays the
same (up to isomorphisms):</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">g_</span> <span class="o">=</span> <span class="n">Fatgraph</span><span class="o">.</span><span class="n">bridge2</span><span class="p">(</span><span class="n">g2</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="n">g1</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">g</span> <span class="o">==</span> <span class="n">g_</span>
<span class="go">True</span>
</pre></div>
</div>
<p><em>Caveat:</em> If <cite>self == other</cite> then the resulting graph is made
up of <em>two copies</em> of <cite>self</cite> with a new edge connecting
<cite>edge1</cite> on one copy and <cite>edge2</cite> on the other.</p>
</dd></dl>

<dl class="method">
<dt id="fatghol.rg.Fatgraph.compute_boundary_cycles">
<tt class="descname">compute_boundary_cycles</tt><big>(</big><big>)</big><a class="reference internal" href="_modules/fatghol/rg.html#Fatgraph.compute_boundary_cycles"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.rg.Fatgraph.compute_boundary_cycles" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a list of boundary cycles of this <cite>Fatgraph</cite> object.</p>
<p>Boundary cycles are represented as a cyclic list of &#8216;corners&#8217;:
a corner is a triple <cite>(v, i, j)</cite> consisting of a vertex and
two consecutive indices (in the cyclic order, so, either <cite>j ==
i+1</cite> or <cite>i</cite> and <cite>j</cite> are the starting and ending indices):</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">Fatgraph</span><span class="p">([</span><span class="n">Vertex</span><span class="p">([</span><span class="mi">2</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">0</span><span class="p">]),</span><span class="n">Vertex</span><span class="p">([</span><span class="mi">2</span><span class="p">,</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">])])</span><span class="o">.</span><span class="n">compute_boundary_cycles</span><span class="p">()</span>
<span class="go">[BoundaryCycle([(1, 2, 0), (0, 0, 1)]),</span>
<span class="go"> BoundaryCycle([(0, 1, 2), (1, 1, 2)]),</span>
<span class="go"> BoundaryCycle([(0, 2, 0), (1, 0, 1)])]</span>
</pre></div>
</div>
<p>This verbose representation allows one to distinguish the
boundary cycles made from the same set of edges:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">Fatgraph</span><span class="p">([</span><span class="n">Vertex</span><span class="p">([</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">])])</span><span class="o">.</span><span class="n">compute_boundary_cycles</span><span class="p">()</span>
<span class="go">[BoundaryCycle([(0, 2, 3), (0, 4, 5), (0, 0, 1)]),</span>
<span class="go"> BoundaryCycle([(0, 1, 2), (0, 3, 4), (0, 5, 0)])]</span>
</pre></div>
</div>
</dd></dl>

<dl class="method">
<dt id="fatghol.rg.Fatgraph.contract">
<tt class="descname">contract</tt><big>(</big><em>obj</em>, <em>edgeno</em><big>)</big><a class="reference internal" href="_modules/fatghol/rg.html#Fatgraph.contract"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.rg.Fatgraph.contract" title="Permalink to this definition">¶</a></dt>
<dd><p>Return new <cite>Fatgraph</cite> obtained by contracting the specified edge.</p>
<p>Examples:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">Fatgraph</span><span class="p">([</span><span class="n">Vertex</span><span class="p">([</span><span class="mi">2</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">0</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">1</span><span class="p">])])</span><span class="o">.</span><span class="n">contract</span><span class="p">(</span><span class="mi">0</span><span class="p">)</span>
<span class="go">Fatgraph([Vertex([1, 1, 0, 0])])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">Fatgraph</span><span class="p">([</span><span class="n">Vertex</span><span class="p">([</span><span class="mi">2</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">0</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">2</span><span class="p">,</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">])])</span><span class="o">.</span><span class="n">contract</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>
<span class="go">Fatgraph([Vertex([0, 1, 1, 0])])</span>
</pre></div>
</div>
<p>The M_{1,1} trivalent graph yield the same result no matter
what edge is contracted:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">Fatgraph</span><span class="p">([</span><span class="n">Vertex</span><span class="p">([</span><span class="mi">2</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">0</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">2</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">0</span><span class="p">])])</span><span class="o">.</span><span class="n">contract</span><span class="p">(</span><span class="mi">0</span><span class="p">)</span>
<span class="go">Fatgraph([Vertex([1, 0, 1, 0])])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">Fatgraph</span><span class="p">([</span><span class="n">Vertex</span><span class="p">([</span><span class="mi">2</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">0</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">2</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">0</span><span class="p">])])</span><span class="o">.</span><span class="n">contract</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>
<span class="go">Fatgraph([Vertex([0, 1, 0, 1])])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">Fatgraph</span><span class="p">([</span><span class="n">Vertex</span><span class="p">([</span><span class="mi">2</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">0</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">2</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">0</span><span class="p">])])</span><span class="o">.</span><span class="n">contract</span><span class="p">(</span><span class="mi">2</span><span class="p">)</span>
<span class="go">Fatgraph([Vertex([1, 0, 1, 0])])</span>
</pre></div>
</div>
</dd></dl>

<dl class="method">
<dt id="fatghol.rg.Fatgraph.contract_boundary_cycle">
<tt class="descname">contract_boundary_cycle</tt><big>(</big><em>bcy</em>, <em>vi1</em>, <em>vi2</em><big>)</big><a class="reference internal" href="_modules/fatghol/rg.html#Fatgraph.contract_boundary_cycle"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.rg.Fatgraph.contract_boundary_cycle" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a new <cite>BoundaryCycle</cite> instance, image of <cite>bcy</cite> under
the topological map that contracts the edge with endpoints
<cite>(v1,i1)</cite> and <cite>(v2,i2)</cite> that are passed as first and second
argument.</p>
<p>XXX: return <cite>bcy</cite> if neither <cite>v1</cite> nor <cite>v2</cite> are contained in it.</p>
</dd></dl>

<dl class="method">
<dt id="fatghol.rg.Fatgraph.edge_orbits">
<tt class="descname">edge_orbits</tt><big>(</big><em>obj</em><big>)</big><a class="reference internal" href="_modules/fatghol/rg.html#Fatgraph.edge_orbits"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.rg.Fatgraph.edge_orbits" title="Permalink to this definition">¶</a></dt>
<dd><p>Compute orbits of the edges under the action of graph
automorphism group, and a representative for each orbit.</p>
<p>Returns a dictionary, whose keys are the representatives, and
whose values are the orbits.  Orbits are represented as Python
<cite>set</cite> objects.</p>
<p>Examples:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">Fatgraph</span><span class="p">([</span><span class="n">Vertex</span><span class="p">([</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">])])</span><span class="o">.</span><span class="n">edge_orbits</span><span class="p">()</span>
<span class="go">{0: set([0, 1, 2])}</span>

<span class="gp">&gt;&gt;&gt; </span><span class="n">Fatgraph</span><span class="p">([</span><span class="n">Vertex</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">2</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">2</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">0</span><span class="p">])])</span><span class="o">.</span><span class="n">edge_orbits</span><span class="p">()</span>
<span class="go">{0: set([0, 1, 2])}</span>
</pre></div>
</div>
</dd></dl>

<dl class="method">
<dt id="fatghol.rg.Fatgraph.edge_pair_orbits">
<tt class="descname">edge_pair_orbits</tt><big>(</big><em>obj</em><big>)</big><a class="reference internal" href="_modules/fatghol/rg.html#Fatgraph.edge_pair_orbits"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.rg.Fatgraph.edge_pair_orbits" title="Permalink to this definition">¶</a></dt>
<dd><p>Compute orbits of pairs <cite>(edge1, edge2)</cite> under the action
of graph automorphism group, and a representative for each
orbit.</p>
<p>Returns a dictionary, whose keys are the representatives, and
whose values are the orbits.  Orbits are represented as Python
<cite>set</cite> objects.</p>
<p>Examples:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">Fatgraph</span><span class="p">([</span><span class="n">Vertex</span><span class="p">([</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">])])</span><span class="o">.</span><span class="n">edge_pair_orbits</span><span class="p">()</span>
<span class="go">{(0, 1): set([(0, 1), (1, 2), (2, 0)]),</span>
<span class="go"> (0, 0): set([(0, 0), (1, 1), (2, 2)]),</span>
<span class="go"> (0, 2): set([(1, 0), (0, 2), (2, 1)])}</span>
</pre></div>
</div>
</dd></dl>

<dl class="attribute">
<dt id="fatghol.rg.Fatgraph.endpoints">
<tt class="descname">endpoints</tt><a class="reference internal" href="_modules/fatghol/rg.html#Fatgraph.endpoints"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.rg.Fatgraph.endpoints" title="Permalink to this definition">¶</a></dt>
<dd><p>Adjacency list of this graph.  For each edge, store a pair
<cite>(v1, v2)</cite> where <cite>v1</cite> and <cite>v2</cite> are (indices of)
endpoint vertices of an edge, and a corresponding pair
<cite>(i1, i2)</cite> where <cite>i1</cite> and <cite>i2</cite> are indices of the given
edge in vertices <cite>v1</cite> and <cite>v2</cite>.
Each pair <cite>(v, i)</cite> represents a flag by the endpoint
vertex and the index of the edge in the vertex.  (The
vertex index alone is not enough for representing the
edge arrow for loops.)</p>
</dd></dl>

<dl class="method">
<dt id="fatghol.rg.Fatgraph.hangcircle">
<tt class="descname">hangcircle</tt><big>(</big><em>edge</em>, <em>side</em><big>)</big><a class="reference internal" href="_modules/fatghol/rg.html#Fatgraph.hangcircle"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.rg.Fatgraph.hangcircle" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a new <cite>Fatgraph</cite>, formed by attaching a circle with
a new edge to a new trivalent vertex in the middle of <cite>edge</cite>.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">g</span> <span class="o">=</span> <span class="n">Fatgraph</span><span class="p">([</span><span class="n">Vertex</span><span class="p">([</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">0</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">1</span><span class="p">])])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">g1</span> <span class="o">=</span> <span class="n">g</span><span class="o">.</span><span class="n">hangcircle</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">g1</span> <span class="ow">is</span> <span class="n">g</span>
<span class="go">False</span>
</pre></div>
</div>
<p>Argument <cite>side</cite> controls which side of <cite>edge</cite> the circle is
hung to (valid values are 0 or 1), i.e., which of the two
inequivalent cyclic orders the new trivalent vertices will be
given:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">g</span> <span class="o">=</span> <span class="n">Fatgraph</span><span class="p">([</span><span class="n">Vertex</span><span class="p">([</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">0</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">1</span><span class="p">])])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">g1</span> <span class="o">=</span> <span class="n">g</span><span class="o">.</span><span class="n">hangcircle</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">g1</span> <span class="o">==</span> <span class="n">Fatgraph</span><span class="p">([</span><span class="n">Vertex</span><span class="p">([</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">3</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">1</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">0</span><span class="p">,</span><span class="mi">3</span><span class="p">,</span><span class="mi">4</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">5</span><span class="p">,</span><span class="mi">5</span><span class="p">,</span><span class="mi">4</span><span class="p">])])</span>
<span class="go">True</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">g2</span> <span class="o">=</span> <span class="n">g</span><span class="o">.</span><span class="n">hangcircle</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">g2</span> <span class="o">==</span> <span class="n">Fatgraph</span><span class="p">([</span><span class="n">Vertex</span><span class="p">([</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">3</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">1</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">3</span><span class="p">,</span><span class="mi">0</span><span class="p">,</span><span class="mi">4</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">5</span><span class="p">,</span><span class="mi">5</span><span class="p">,</span><span class="mi">4</span><span class="p">])])</span>
<span class="go">True</span>
</pre></div>
</div>
<p>It is worth noting that the new graph will have 3 edges more
than the original one:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">g1</span><span class="o">.</span><span class="n">num_edges</span> <span class="o">==</span> <span class="n">g</span><span class="o">.</span><span class="n">num_edges</span> <span class="o">+</span> <span class="mi">3</span>
<span class="go">True</span>
</pre></div>
</div>
</dd></dl>

<dl class="method">
<dt id="fatghol.rg.Fatgraph.is_loop">
<tt class="descname">is_loop</tt><big>(</big><em>edge</em><big>)</big><a class="reference internal" href="_modules/fatghol/rg.html#Fatgraph.is_loop"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.rg.Fatgraph.is_loop" title="Permalink to this definition">¶</a></dt>
<dd><p>Return <cite>True</cite> if <cite>edge</cite> is a loop (i.e., the two endpoint coincide).</p>
</dd></dl>

<dl class="method">
<dt id="fatghol.rg.Fatgraph.is_oriented">
<tt class="descname">is_oriented</tt><big>(</big><big>)</big><a class="reference internal" href="_modules/fatghol/rg.html#Fatgraph.is_oriented"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.rg.Fatgraph.is_oriented" title="Permalink to this definition">¶</a></dt>
<dd><p>Return <cite>True</cite> if <cite>Fatgraph</cite> is orientable.</p>
<p>A <cite>Fatgraph</cite> is orientable iff it has no orientation-reversing
automorphism.</p>
<p>Enumerate all automorphisms, end exit with <cite>False</cite> result as
soon as one orientation-reversing one is found.</p>
<p>Examples:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">Fatgraph</span><span class="p">([</span><span class="n">Vertex</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">0</span><span class="p">])])</span><span class="o">.</span><span class="n">is_oriented</span><span class="p">()</span>
<span class="go">False</span>

<span class="gp">&gt;&gt;&gt; </span><span class="n">Fatgraph</span><span class="p">([</span><span class="n">Vertex</span><span class="p">([</span><span class="mi">2</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">2</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">])])</span><span class="o">.</span><span class="n">is_oriented</span><span class="p">()</span>
<span class="go">True</span>

<span class="gp">&gt;&gt;&gt; </span><span class="n">Fatgraph</span><span class="p">([</span><span class="n">Vertex</span><span class="p">([</span><span class="mi">2</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">0</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">2</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">])])</span><span class="o">.</span><span class="n">is_oriented</span><span class="p">()</span>
<span class="go">False</span>

<span class="gp">&gt;&gt;&gt; </span><span class="n">Fatgraph</span><span class="p">([</span><span class="n">Vertex</span><span class="p">([</span><span class="mi">2</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">2</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">])])</span><span class="o">.</span><span class="n">is_oriented</span><span class="p">()</span>
<span class="go">False</span>

<span class="gp">&gt;&gt;&gt; </span><span class="n">Fatgraph</span><span class="p">([</span><span class="n">Vertex</span><span class="p">([</span><span class="mi">3</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">3</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">0</span><span class="p">])],</span>                     <span class="n">numbering</span><span class="o">=</span><span class="p">[(</span><span class="mi">0</span><span class="p">,</span> <span class="n">CyclicTuple</span><span class="p">((</span><span class="mi">2</span><span class="p">,))),</span>                                 <span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="n">CyclicTuple</span><span class="p">((</span><span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">))),</span>                                 <span class="p">(</span><span class="mi">2</span><span class="p">,</span> <span class="n">CyclicTuple</span><span class="p">((</span><span class="mi">3</span><span class="p">,</span> <span class="mi">1</span><span class="p">))),</span>                                 <span class="p">(</span><span class="mi">3</span><span class="p">,</span> <span class="n">CyclicTuple</span><span class="p">((</span><span class="mi">0</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">2</span><span class="p">)))</span> <span class="p">])</span>                                <span class="o">.</span><span class="n">is_oriented</span><span class="p">()</span>
<span class="go">True</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">Fatgraph</span><span class="p">([</span><span class="n">Vertex</span><span class="p">([</span><span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">1</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">2</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">])],</span>                        <span class="n">numbering</span><span class="o">=</span><span class="p">[(</span><span class="mi">0</span><span class="p">,</span> <span class="n">CyclicTuple</span><span class="p">((</span><span class="mi">0</span><span class="p">,))),</span>                                    <span class="p">(</span><span class="mi">2</span><span class="p">,</span> <span class="n">CyclicTuple</span><span class="p">((</span><span class="mi">1</span><span class="p">,</span> <span class="mi">3</span><span class="p">))),</span>                                    <span class="p">(</span><span class="mi">3</span><span class="p">,</span> <span class="n">CyclicTuple</span><span class="p">((</span><span class="mi">3</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">2</span><span class="p">))),</span>                                    <span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="n">CyclicTuple</span><span class="p">((</span><span class="mi">2</span><span class="p">,</span> <span class="mi">1</span><span class="p">)))</span> <span class="p">])</span>                                <span class="o">.</span><span class="n">is_oriented</span><span class="p">()</span>
<span class="go">True</span>
</pre></div>
</div>
</dd></dl>

<dl class="method">
<dt id="fatghol.rg.Fatgraph.isomorphisms">
<tt class="descname">isomorphisms</tt><big>(</big><em>o1</em>, <em>o2</em><big>)</big><a class="reference internal" href="_modules/fatghol/rg.html#Fatgraph.isomorphisms"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.rg.Fatgraph.isomorphisms" title="Permalink to this definition">¶</a></dt>
<dd><p>Iterate over <cite>Fatgraph</cite> isomorphisms from <cite>G1</cite> to <cite>G2</cite>.</p>
<p>An isomorphism is represented by a tuple <cite>(pv, rot, pe)</cite> where:</p>
<blockquote>
<div><ul class="simple">
<li><cite>pv</cite> is a permutation of ther vertices: the <cite>i</cite>-th vertex
of <cite>G1</cite> is sent to the <cite>pv[i]</cite>-th vertex of <cite>G2</cite>, rotated
by <cite>rot[i]</cite> places leftwards;</li>
<li><cite>pe</cite> is a permutation of the edges: edge <cite>i</cite> in <cite>G1</cite> is
mapped to edge <cite>pe[i]</cite> in <cite>G2</cite>.</li>
</ul>
</div></blockquote>
<p>This method can iterate over the automorphism group of a
graph:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">G1</span> <span class="o">=</span> <span class="n">Fatgraph</span><span class="p">([</span><span class="n">Vertex</span><span class="p">([</span><span class="mi">2</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">2</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">])])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">for</span> <span class="n">f</span> <span class="ow">in</span> <span class="n">G1</span><span class="o">.</span><span class="n">isomorphisms</span><span class="p">(</span><span class="n">G1</span><span class="p">):</span> <span class="k">print</span> <span class="n">f</span>
<span class="go">({0: 0, 1: 1}, [0, 0], {0: 0, 1: 1, 2: 2})</span>
<span class="go">({0: 1, 1: 0}, [0, 0], {0: 1, 1: 0, 2: 2})</span>
</pre></div>
</div>
<p>Or it can find the isomorphisms between two given graphs:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">G2</span> <span class="o">=</span> <span class="n">Fatgraph</span><span class="p">([</span><span class="n">Vertex</span><span class="p">([</span><span class="mi">2</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">0</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">0</span><span class="p">])])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">for</span> <span class="n">f</span> <span class="ow">in</span> <span class="n">G1</span><span class="o">.</span><span class="n">isomorphisms</span><span class="p">(</span><span class="n">G2</span><span class="p">):</span> <span class="k">print</span> <span class="n">f</span>
<span class="go">({0: 0, 1: 1}, [2, 2], {0: 1, 1: 2, 2: 0})</span>
<span class="go">({0: 1, 1: 0}, [2, 2], {0: 2, 1: 1, 2: 0})</span>
</pre></div>
</div>
<p>If there are no isomorphisms connecting the two graphs, then no
item is returned by the iterator:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">g3</span> <span class="o">=</span> <span class="n">Fatgraph</span><span class="p">([</span><span class="n">Vertex</span><span class="p">([</span><span class="mi">2</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">0</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">2</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">])])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">list</span><span class="p">(</span><span class="n">G1</span><span class="o">.</span><span class="n">isomorphisms</span><span class="p">(</span><span class="n">g3</span><span class="p">))</span>
<span class="go">[]</span>
</pre></div>
</div>
<p>A concrete example taken from <a href="#id5"><span class="problematic" id="id6">`M_{1,4}`:latex:</span></a></p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">g1</span> <span class="o">=</span> <span class="n">Fatgraph</span><span class="p">([</span><span class="n">Vertex</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">2</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">2</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">5</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">0</span><span class="p">,</span> <span class="mi">4</span><span class="p">,</span> <span class="mi">3</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">8</span><span class="p">,</span> <span class="mi">5</span><span class="p">,</span> <span class="mi">6</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">3</span><span class="p">,</span> <span class="mi">6</span><span class="p">,</span> <span class="mi">7</span><span class="p">,</span> <span class="mi">7</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">8</span><span class="p">,</span> <span class="mi">4</span><span class="p">,</span> <span class="mi">9</span><span class="p">,</span> <span class="mi">9</span><span class="p">])])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">g2</span> <span class="o">=</span> <span class="n">Fatgraph</span><span class="p">([</span><span class="n">Vertex</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">5</span><span class="p">,</span> <span class="mi">6</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">2</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">5</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">8</span><span class="p">,</span> <span class="mi">4</span><span class="p">,</span> <span class="mi">3</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">7</span><span class="p">,</span> <span class="mi">7</span><span class="p">,</span> <span class="mi">6</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">4</span><span class="p">,</span> <span class="mi">8</span><span class="p">,</span> <span class="mi">9</span><span class="p">,</span> <span class="mi">9</span><span class="p">])])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">len</span><span class="p">(</span><span class="nb">list</span><span class="p">(</span><span class="n">Fatgraph</span><span class="o">.</span><span class="n">isomorphisms</span><span class="p">(</span><span class="n">g1</span><span class="p">,</span> <span class="n">g2</span><span class="p">)))</span>
<span class="go">0</span>
</pre></div>
</div>
</dd></dl>

<dl class="method">
<dt id="fatghol.rg.Fatgraph.num_automorphisms">
<tt class="descname">num_automorphisms</tt><big>(</big><big>)</big><a class="reference internal" href="_modules/fatghol/rg.html#Fatgraph.num_automorphisms"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.rg.Fatgraph.num_automorphisms" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the cardinality of the automorphism group of this
<cite>Fatgraph</cite> object.</p>
<p>Examples:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">Fatgraph</span><span class="p">([</span><span class="n">Vertex</span><span class="p">([</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">0</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">1</span><span class="p">])])</span><span class="o">.</span><span class="n">num_automorphisms</span><span class="p">()</span>
<span class="go">6</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">Fatgraph</span><span class="p">([</span><span class="n">Vertex</span><span class="p">([</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">1</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">0</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">2</span><span class="p">])])</span><span class="o">.</span><span class="n">num_automorphisms</span><span class="p">()</span>
<span class="go">2</span>
</pre></div>
</div>
</dd></dl>

<dl class="attribute">
<dt id="fatghol.rg.Fatgraph.num_edges">
<tt class="descname">num_edges</tt><a class="headerlink" href="#fatghol.rg.Fatgraph.num_edges" title="Permalink to this definition">¶</a></dt>
<dd><p>Number of edge colors</p>
</dd></dl>

<dl class="attribute">
<dt id="fatghol.rg.Fatgraph.num_vertices">
<tt class="descname">num_vertices</tt><a class="headerlink" href="#fatghol.rg.Fatgraph.num_vertices" title="Permalink to this definition">¶</a></dt>
<dd><p>Number of vertices  XXX: why is this settable with kwarg???</p>
</dd></dl>

<dl class="attribute">
<dt id="fatghol.rg.Fatgraph.vertices">
<tt class="descname">vertices</tt><a class="headerlink" href="#fatghol.rg.Fatgraph.vertices" title="Permalink to this definition">¶</a></dt>
<dd><p>list of vertices</p>
</dd></dl>

</dd></dl>

<dl class="class">
<dt id="fatghol.rg.Isomorphism">
<em class="property">class </em><tt class="descclassname">fatghol.rg.</tt><tt class="descname">Isomorphism</tt><big>(</big><em>source</em>, <em>target</em>, <em>pv</em>, <em>rot</em>, <em>pe</em><big>)</big><a class="reference internal" href="_modules/fatghol/rg.html#Isomorphism"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.rg.Isomorphism" title="Permalink to this definition">¶</a></dt>
<dd><p>An isomorphism of <cite>Fatgraphs</cite>.</p>
<dl class="method">
<dt id="fatghol.rg.Isomorphism.compare_orientations">
<tt class="descname">compare_orientations</tt><big>(</big><big>)</big><a class="reference internal" href="_modules/fatghol/rg.html#Isomorphism.compare_orientations"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.rg.Isomorphism.compare_orientations" title="Permalink to this definition">¶</a></dt>
<dd><p>Return +1 or -1 depending on whether the orientations of
the target Fatgraph pulls back to the orientation of the
source Fatgraph via this <cite>Isomorphism</cite>.</p>
</dd></dl>

<dl class="method">
<dt id="fatghol.rg.Isomorphism.is_identity">
<tt class="descname">is_identity</tt><big>(</big><big>)</big><a class="reference internal" href="_modules/fatghol/rg.html#Isomorphism.is_identity"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.rg.Isomorphism.is_identity" title="Permalink to this definition">¶</a></dt>
<dd><p>Return <cite>True</cite> if this is the identity morphism.</p>
<p>Only makes sense for automorphisms, so an <cite>AssertionException</cite>
is raised if source and target differ.</p>
</dd></dl>

<dl class="method">
<dt id="fatghol.rg.Isomorphism.is_orientation_reversing">
<tt class="descname">is_orientation_reversing</tt><big>(</big><big>)</big><a class="reference internal" href="_modules/fatghol/rg.html#Isomorphism.is_orientation_reversing"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.rg.Isomorphism.is_orientation_reversing" title="Permalink to this definition">¶</a></dt>
<dd><p>Return <cite>True</cite> if this <cite>Isomorphism</cite> reverses orientation on
the source and target <cite>Fatgraph</cite> instances.</p>
</dd></dl>

<dl class="method">
<dt id="fatghol.rg.Isomorphism.transform_boundary_cycle">
<tt class="descname">transform_boundary_cycle</tt><big>(</big><em>bcy</em><big>)</big><a class="reference internal" href="_modules/fatghol/rg.html#Isomorphism.transform_boundary_cycle"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.rg.Isomorphism.transform_boundary_cycle" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a new <cite>BoundaryCycle</cite> instance, obtained by
transforming each corner according to a graph isomorphism.</p>
</dd></dl>

</dd></dl>

<dl class="class">
<dt id="fatghol.rg.MgnGraphsIterator">
<em class="property">class </em><tt class="descclassname">fatghol.rg.</tt><tt class="descname">MgnGraphsIterator</tt><big>(</big><em>g</em>, <em>n</em><big>)</big><a class="reference internal" href="_modules/fatghol/rg.html#MgnGraphsIterator"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.rg.MgnGraphsIterator" title="Permalink to this definition">¶</a></dt>
<dd><p>Iterate over all connected fatgraphs having the
prescribed genus <cite>g</cite> and number of boundary cycles <cite>n</cite>.</p>
<p>Examples:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="k">for</span> <span class="n">g</span> <span class="ow">in</span> <span class="n">MgnGraphsIterator</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span><span class="mi">3</span><span class="p">):</span> <span class="k">print</span> <span class="n">g</span>
<span class="go">Fatgraph([Vertex([1, 2, 1]), Vertex([2, 0, 0])]) </span>
<span class="go">Fatgraph([Vertex([1, 0, 2]), Vertex([2, 0, 1])])</span>
<span class="go">Fatgraph([Vertex([1, 1, 0, 0])])</span>

<span class="gp">&gt;&gt;&gt; </span><span class="k">for</span> <span class="n">g</span> <span class="ow">in</span> <span class="n">MgnGraphsIterator</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span><span class="mi">1</span><span class="p">):</span> <span class="k">print</span> <span class="n">g</span>
<span class="go">Fatgraph([Vertex([1, 0, 2]), Vertex([2, 1, 0])])</span>
<span class="go">Fatgraph([Vertex([1, 0, 1, 0])])</span>
</pre></div>
</div>
<dl class="attribute">
<dt id="fatghol.rg.MgnGraphsIterator.g">
<tt class="descname">g</tt><a class="headerlink" href="#fatghol.rg.MgnGraphsIterator.g" title="Permalink to this definition">¶</a></dt>
<dd><p>Prescribed genus of returned graphs</p>
</dd></dl>

<dl class="attribute">
<dt id="fatghol.rg.MgnGraphsIterator.n">
<tt class="descname">n</tt><a class="headerlink" href="#fatghol.rg.MgnGraphsIterator.n" title="Permalink to this definition">¶</a></dt>
<dd><p>Prescribed number of boundary components</p>
</dd></dl>

</dd></dl>

<dl class="function">
<dt id="fatghol.rg.MgnTrivalentGraphsRecursiveGenerator">
<tt class="descclassname">fatghol.rg.</tt><tt class="descname">MgnTrivalentGraphsRecursiveGenerator</tt><big>(</big><em>g</em>, <em>n</em><big>)</big><a class="reference internal" href="_modules/fatghol/rg.html#MgnTrivalentGraphsRecursiveGenerator"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.rg.MgnTrivalentGraphsRecursiveGenerator" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a list of all connected trivalent fatgraphs having the
prescribed genus <cite>g</cite> and number of boundary cycles <cite>n</cite>.</p>
<p>Examples:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="k">for</span> <span class="n">g</span> <span class="ow">in</span> <span class="n">MgnTrivalentGraphsRecursiveGenerator</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span><span class="mi">3</span><span class="p">):</span> <span class="k">print</span> <span class="n">g</span>
<span class="go">Fatgraph([Vertex([1, 2, 1]), Vertex([2, 0, 0])]) </span>
<span class="go">Fatgraph([Vertex([1, 0, 2]), Vertex([2, 0, 1])])</span>

<span class="gp">&gt;&gt;&gt; </span><span class="k">for</span> <span class="n">g</span> <span class="ow">in</span> <span class="n">MgnTrivalentGraphsRecursiveGenerator</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span><span class="mi">1</span><span class="p">):</span> <span class="k">print</span> <span class="n">g</span>
<span class="go">Fatgraph([Vertex([1, 0, 2]), Vertex([2, 1, 0])])</span>
</pre></div>
</div>
</dd></dl>

<dl class="class">
<dt id="fatghol.rg.Vertex">
<em class="property">class </em><tt class="descclassname">fatghol.rg.</tt><tt class="descname">Vertex</tt><big>(</big><em>seq</em><big>)</big><a class="reference internal" href="_modules/fatghol/rg.html#Vertex"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.rg.Vertex" title="Permalink to this definition">¶</a></dt>
<dd><p>A (representative of) a vertex of a ribbon graph.</p>
<p>A vertex is represented by the cyclically ordered list of its
(decorated) edges.  The edge colorings may be accessed through a
(read-only) sequence interface.</p>
<p>At init time, the number of loops attached to this vertex is
computed and stored in the <cite>.num_loops</cite> attribute:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">Vertex</span><span class="p">([</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">])</span><span class="o">.</span><span class="n">num_loops</span>
<span class="go">0</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">Vertex</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">0</span><span class="p">,</span><span class="mi">0</span><span class="p">])</span><span class="o">.</span><span class="n">num_loops</span>
<span class="go">2</span>
</pre></div>
</div>
</dd></dl>

</div>
<div class="section" id="module-fatghol.homology">
<span id="fatghol-homology"></span><h3><cite>fatghol.homology</cite><a class="headerlink" href="#module-fatghol.homology" title="Permalink to this headline">¶</a></h3>
<p>Generic classes for homological algebra.</p>
<dl class="class">
<dt id="fatghol.homology.ChainComplex">
<em class="property">class </em><tt class="descclassname">fatghol.homology.</tt><tt class="descname">ChainComplex</tt><big>(</big><em>length</em><big>)</big><a class="reference internal" href="_modules/fatghol/homology.html#ChainComplex"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.homology.ChainComplex" title="Permalink to this definition">¶</a></dt>
<dd><p>Represents a (finite-length) chain (homology) complex.</p>
<p>A <cite>ChainComplex</cite> <cite>C</cite> of length <cite>l</cite> comprises vector spaces <cite>C[i]</cite>
and differentials <cite>C.differential[i]</cite>; each <cite>C[i]</cite> represents the
part of the graded vector space <cite>C</cite> having degree <cite>i</cite>.  The map
<cite>C.differential[i]</cite> sends (linear combinations of) elements in
vector space <cite>C[i]</cite> to linear combinations of vectors in <cite>C[i-1]</cite>;
the <cite>coordinates</cite> method of <cite>C[i-1]</cite> will be used to obtain a
numerical representation of the differentiated element.</p>
<p>A <cite>ChainComplex</cite> instance must be initialized by assigning
<cite>VectorSpace</cite> instances into each <cite>C[i]</cite> (for 0 &lt;= <cite>i</cite> &lt;
<cite>len(C)</cite>), and appropriate maps into <cite>C.differential[i]</cite> (for 1 &lt;=
<cite>i</cite> &lt; <cite>len(C)</cite>):</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="c"># chain homology of a segment</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">C</span> <span class="o">=</span> <span class="n">ChainComplex</span><span class="p">(</span><span class="mi">2</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">C</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span> <span class="o">=</span> <span class="n">VectorSpace</span><span class="p">([</span><span class="s">&#39;a&#39;</span><span class="p">])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">C</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span> <span class="o">=</span> <span class="n">VectorSpace</span><span class="p">([</span><span class="s">&#39;b0&#39;</span><span class="p">,</span> <span class="s">&#39;b1&#39;</span><span class="p">])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">C</span><span class="o">.</span><span class="n">differential</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span> <span class="o">=</span> <span class="k">lambda</span> <span class="n">_</span><span class="p">:</span> <span class="p">[(</span><span class="s">&#39;b0&#39;</span><span class="p">,</span><span class="mi">1</span><span class="p">),</span> <span class="p">(</span><span class="s">&#39;b1&#39;</span><span class="p">,</span> <span class="o">-</span><span class="mi">1</span><span class="p">)]</span>
</pre></div>
</div>
<p>Indices of the slices <cite>C[i]</cite> run from 0 to <cite>len(C)-1</cite> (inclusive).
The Python <cite>len</cite> operator returns the total length of the
complex:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="nb">len</span><span class="p">(</span><span class="n">C</span><span class="p">)</span>
<span class="go">2</span>
</pre></div>
</div>
<p>At present, the only supported operation on chain complexes is
computing the rank of homology groups:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">C</span><span class="o">.</span><span class="n">compute_homology_ranks</span><span class="p">()</span>
<span class="go">[1, 0]</span>
</pre></div>
</div>
<dl class="method">
<dt id="fatghol.homology.ChainComplex.compute_boundary_operators">
<tt class="descname">compute_boundary_operators</tt><big>(</big><big>)</big><a class="reference internal" href="_modules/fatghol/homology.html#ChainComplex.compute_boundary_operators"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.homology.ChainComplex.compute_boundary_operators" title="Permalink to this definition">¶</a></dt>
<dd><p>Compute and return matrix form of boundary operators.</p>
<p>Return list of sparse <cite>SimpleMatrix</cite> instances.</p>
<p>Matrix form of boundary operators operates on column vectors:
the <cite>i</cite>-th differential <cite>D[i]</cite> is <cite>dim C[i-1]</cite> rows (range) by
<cite>dim C[i]</cite> columns (domain).</p>
</dd></dl>

<dl class="method">
<dt id="fatghol.homology.ChainComplex.compute_homology_ranks">
<tt class="descname">compute_homology_ranks</tt><big>(</big><big>)</big><a class="reference internal" href="_modules/fatghol/homology.html#ChainComplex.compute_homology_ranks"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.homology.ChainComplex.compute_homology_ranks" title="Permalink to this definition">¶</a></dt>
<dd><p>Compute and return (list of) homology group ranks.</p>
<p>Returns a list of integers: item at index <cite>n</cite> is the rank of
the <cite>n</cite>-th homology group of this chain complex.  Since the
chain complex has finite length, homology group indices can
only run from 0 to the length of the complex (all other groups
being, trivially, null).</p>
<p>Examples:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="c"># chain homology of a point</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">C_point</span> <span class="o">=</span> <span class="n">ChainComplex</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">C_point</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span> <span class="o">=</span> <span class="n">VectorSpace</span><span class="p">([</span><span class="s">&#39;a&#39;</span><span class="p">])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">C_point</span><span class="o">.</span><span class="n">compute_homology_ranks</span><span class="p">()</span>
<span class="go">[1]</span>

<span class="gp">&gt;&gt;&gt; </span><span class="c"># chain homology of a segment</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">C_segment</span> <span class="o">=</span> <span class="n">ChainComplex</span><span class="p">(</span><span class="mi">2</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">C_segment</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span> <span class="o">=</span> <span class="n">VectorSpace</span><span class="p">([</span><span class="s">&#39;a&#39;</span><span class="p">])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">C_segment</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span> <span class="o">=</span> <span class="n">VectorSpace</span><span class="p">([</span><span class="s">&#39;b0&#39;</span><span class="p">,</span> <span class="s">&#39;b1&#39;</span><span class="p">])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">C_segment</span><span class="o">.</span><span class="n">differential</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span> <span class="o">=</span> <span class="k">lambda</span> <span class="n">_</span><span class="p">:</span> <span class="p">[(</span><span class="s">&#39;b0&#39;</span><span class="p">,</span><span class="mi">1</span><span class="p">),</span> <span class="p">(</span><span class="s">&#39;b1&#39;</span><span class="p">,</span> <span class="o">-</span><span class="mi">1</span><span class="p">)]</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">C_segment</span><span class="o">.</span><span class="n">compute_homology_ranks</span><span class="p">()</span>
<span class="go">[1, 0]</span>

<span class="gp">&gt;&gt;&gt; </span><span class="c"># chain homology of a circle</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">C_circle</span> <span class="o">=</span> <span class="n">ChainComplex</span><span class="p">(</span><span class="mi">2</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">C_circle</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span> <span class="o">=</span> <span class="n">VectorSpace</span><span class="p">([</span><span class="s">&#39;a&#39;</span><span class="p">])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">C_circle</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span> <span class="o">=</span> <span class="n">VectorSpace</span><span class="p">([</span><span class="s">&#39;b&#39;</span><span class="p">])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">C_circle</span><span class="o">.</span><span class="n">differential</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span> <span class="o">=</span> <span class="k">lambda</span> <span class="n">_</span><span class="p">:</span> <span class="p">[]</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">C_circle</span><span class="o">.</span><span class="n">compute_homology_ranks</span><span class="p">()</span>
<span class="go">[1, 1]</span>
</pre></div>
</div>
</dd></dl>

<dl class="attribute">
<dt id="fatghol.homology.ChainComplex.differential">
<tt class="descname">differential</tt><a class="headerlink" href="#fatghol.homology.ChainComplex.differential" title="Permalink to this definition">¶</a></dt>
<dd><p>Boundary operators; <cite>differentials[i]</cite> sends elements in</p>
</dd></dl>

<dl class="attribute">
<dt id="fatghol.homology.ChainComplex.length">
<tt class="descname">length</tt><a class="headerlink" href="#fatghol.homology.ChainComplex.length" title="Permalink to this definition">¶</a></dt>
<dd><p>Total length of the complex.</p>
</dd></dl>

<dl class="attribute">
<dt id="fatghol.homology.ChainComplex.module">
<tt class="descname">module</tt><a class="headerlink" href="#fatghol.homology.ChainComplex.module" title="Permalink to this definition">¶</a></dt>
<dd><p>The vectotr spaces supporting the differential complex</p>
</dd></dl>

</dd></dl>

<dl class="class">
<dt id="fatghol.homology.DifferentialComplex">
<em class="property">class </em><tt class="descclassname">fatghol.homology.</tt><tt class="descname">DifferentialComplex</tt><big>(</big><em>len_or_bds=</em><span class="optional">[</span><span class="optional">]</span><big>)</big><a class="reference internal" href="_modules/fatghol/homology.html#DifferentialComplex"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.homology.DifferentialComplex" title="Permalink to this definition">¶</a></dt>
<dd><p>A finite-length complex of differential operators.</p>
<p>A <cite>DifferentialComplex</cite> is an ordered sequence of differential
operators <cite>D[i]</cite>; each <cite>D[i]</cite> maps <cite>C[i]</cite> into <cite>C[i+1]</cite>.  The
differential operators <em>must</em> be instances of the <cite>SimpleMatrix</cite>
class; matrices are assumed to operate on column vectors, so that
the number of rows equals the dimension of the domain vector
space.</p>
<p>Indices of the operators <cite>D[i]</cite> run from 0 to <cite>len(D)-1</cite>
(inclusive).  The Python <cite>len</cite> operator returns the total length
of the complex:</p>
<div class="highlight-python"><pre>| &gt;&gt;&gt; len(D)
| 2</pre>
</div>
<p>At present, the only supported operation on differential complexes
is computing the rank of homology groups:</p>
<div class="highlight-python"><pre>| &gt;&gt;&gt; D.compute_homology_ranks()
| [1, 0]</pre>
</div>
<p>An assertion is thrown if the matrix product of
<cite>D[i]</cite> and <cite>D[i+1]</cite> is not null.</p>
<dl class="method">
<dt id="fatghol.homology.DifferentialComplex.compute_homology_ranks">
<tt class="descname">compute_homology_ranks</tt><big>(</big><big>)</big><a class="reference internal" href="_modules/fatghol/homology.html#DifferentialComplex.compute_homology_ranks"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.homology.DifferentialComplex.compute_homology_ranks" title="Permalink to this definition">¶</a></dt>
<dd><p>Compute and return (list of) homology group ranks.</p>
<p>Returns a list of integers: item at index <cite>n</cite> is the rank of
the <cite>n</cite>-th homology group of this differential complex.  Since
the differential complex has finite length, homology group
indices can only run from 0 to the length of the complex (all
other groups being, trivially, null).</p>
</dd></dl>

</dd></dl>

<dl class="class">
<dt id="fatghol.homology.VectorSpace">
<em class="property">class </em><tt class="descclassname">fatghol.homology.</tt><tt class="descname">VectorSpace</tt><big>(</big><em>base</em><big>)</big><a class="reference internal" href="_modules/fatghol/homology.html#VectorSpace"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.homology.VectorSpace" title="Permalink to this definition">¶</a></dt>
<dd><p>Represent the vector space generated by the given <cite>base</cite> vectors.</p>
<p>After construction, you can retrieve the base vectors set and the
dimension from instance attributes <cite>base</cite> and <cite>dimension</cite>.</p>
<p>The <cite>base</cite> elements are assumed to be <em>linearly independent</em>, so
the <cite>dimension</cite> of the generated vector space equals the number of
elements in the base set.</p>
<dl class="method">
<dt id="fatghol.homology.VectorSpace.coordinates">
<tt class="descname">coordinates</tt><big>(</big><em>combo</em><big>)</big><a class="reference internal" href="_modules/fatghol/homology.html#VectorSpace.coordinates"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.homology.VectorSpace.coordinates" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the (sparse) coordinate vector of <cite>combo</cite>.</p>
<p>Argument <cite>combo</cite> represents a linear combination as a list
of pairs <cite>(vector, coefficient)</cite>, where <cite>vector</cite> is an item in
the <cite>base</cite> (specified when constructing this object).</p>
<p>Return value is a <cite>dict</cite> instance, mapping each <cite>i</cite> to the
component of <cite>combo</cite> w.r.t. to the <cite>i</cite>-th basis vector.</p>
</dd></dl>

</dd></dl>

</div>
<div class="section" id="module-fatghol.graph_homology">
<span id="fatghol-graph-homology"></span><h3><cite>fatghol.graph_homology</cite><a class="headerlink" href="#module-fatghol.graph_homology" title="Permalink to this headline">¶</a></h3>
<p>Classes for computing graph homology.</p>
<dl class="function">
<dt id="fatghol.graph_homology.FatgraphComplex">
<tt class="descclassname">fatghol.graph_homology.</tt><tt class="descname">FatgraphComplex</tt><big>(</big><em>g</em>, <em>n</em><big>)</big><a class="reference internal" href="_modules/fatghol/graph_homology.html#FatgraphComplex"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.graph_homology.FatgraphComplex" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the fatgraph complex for given genus <cite>g</cite> and number of
boundary components <cite>n</cite>.</p>
<p>This is a factory method returning a <cite>homology.ChainComplex</cite>
instance, populated with the correct vector spaces and
differentials to compute the graph homology of the space
<cite>M_{g,n}</cite>.</p>
</dd></dl>

<dl class="class">
<dt id="fatghol.graph_homology.MgnChainComplex">
<em class="property">class </em><tt class="descclassname">fatghol.graph_homology.</tt><tt class="descname">MgnChainComplex</tt><big>(</big><em>length</em><big>)</big><a class="reference internal" href="_modules/fatghol/graph_homology.html#MgnChainComplex"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.graph_homology.MgnChainComplex" title="Permalink to this definition">¶</a></dt>
<dd><p>A specialized <cite>ChainComplex</cite>.</p>
</dd></dl>

<dl class="class">
<dt id="fatghol.graph_homology.NumberedFatgraph">
<em class="property">class </em><tt class="descclassname">fatghol.graph_homology.</tt><tt class="descname">NumberedFatgraph</tt><big>(</big><em>underlying</em>, <em>numbering</em><big>)</big><a class="reference internal" href="_modules/fatghol/graph_homology.html#NumberedFatgraph"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.graph_homology.NumberedFatgraph" title="Permalink to this definition">¶</a></dt>
<dd><p>A <cite>Fatgraph</cite> decorated with a numbering of the boundary components.</p>
<p>A numbered fatgraph is constructed from a <cite>Fatgraph</cite> instance
(called the <em>underlying graph</em>) and a numbering (that is, a
bijective map assigning an integer to each boundary components of
the underlying graph).</p>
<p>Examples:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">ug</span> <span class="o">=</span> <span class="n">Fatgraph</span><span class="p">([</span><span class="n">Vertex</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">0</span><span class="p">])])</span>  <span class="c"># underlying graph</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">ng</span> <span class="o">=</span> <span class="n">NumberedFatgraph</span><span class="p">(</span><span class="n">ug</span><span class="p">,</span>                  <span class="n">numbering</span><span class="o">=</span><span class="p">[(</span><span class="n">BoundaryCycle</span><span class="p">([(</span><span class="mi">0</span><span class="p">,</span><span class="mi">3</span><span class="p">,</span><span class="mi">0</span><span class="p">),</span> <span class="p">(</span><span class="mi">0</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">3</span><span class="p">),</span> <span class="p">(</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">),</span> <span class="p">(</span><span class="mi">0</span><span class="p">,</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">)]),</span> <span class="mi">0</span><span class="p">)])</span>
</pre></div>
</div>
<p>The <cite>numbering</cite> attribute is set to a dictionary mapping the
boundary cycle <cite>bcy</cite> to the integer <cite>n</cite>; for this, a valid <cite>dict</cite>
initializer is needed, which can be:</p>
<blockquote>
<div><ul class="simple">
<li>either a sequence of tuples <cite>(bcy, n)</cite>, where each <cite>n</cite> is
a non-negative integer, and each <cite>bcy</cite> is a
<cite>BoundaryCycle</cite> instance,</li>
<li>or a <cite>dict</cite> instance mapping <cite>BoundaryCycle</cite> instances to
<a href="#id7"><span class="problematic" id="id8">`</span></a>int`s.</li>
</ul>
</div></blockquote>
<dl class="docutils">
<dt>In either case, an assertion is raised if:</dt>
<dd><ul class="first last simple">
<li>the number of pairs in the initializer does not match
the number of boundary cycles;</li>
<li>the set of integer keys is not <cite>[0 .. n]</cite>;</li>
<li>there are duplicate boundary cycles or integers
in the initializer;</li>
</ul>
</dd>
<dt>Examples::</dt>
<dd><div class="first last highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">ug0</span> <span class="o">=</span> <span class="n">Fatgraph</span><span class="p">([</span><span class="n">Vertex</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">0</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span><span class="mi">0</span><span class="p">,</span><span class="mi">2</span><span class="p">])])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">bc</span> <span class="o">=</span> <span class="n">ug0</span><span class="o">.</span><span class="n">boundary_cycles</span>  <span class="c"># three b.c.&#39;s</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">ng0</span> <span class="o">=</span> <span class="n">NumberedFatgraph</span><span class="p">(</span><span class="n">ug0</span><span class="p">,</span> <span class="p">[</span> <span class="p">(</span><span class="n">bcy</span><span class="p">,</span><span class="n">n</span><span class="p">)</span> <span class="k">for</span> <span class="p">(</span><span class="n">n</span><span class="p">,</span><span class="n">bcy</span><span class="p">)</span> <span class="ow">in</span> <span class="nb">enumerate</span><span class="p">(</span><span class="n">bc</span><span class="p">)])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">ng0</span><span class="o">.</span><span class="n">numbering</span> <span class="o">==</span> <span class="p">{</span>
<span class="gp">... </span>   <span class="n">BoundaryCycle</span><span class="p">([(</span><span class="mi">0</span><span class="p">,</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">),</span> <span class="p">(</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">0</span><span class="p">)]):</span> <span class="mi">0</span><span class="p">,</span> 
<span class="gp">... </span>   <span class="n">BoundaryCycle</span><span class="p">([(</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">),</span> <span class="p">(</span><span class="mi">1</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">)]):</span> <span class="mi">1</span><span class="p">,</span> 
<span class="gp">... </span>   <span class="n">BoundaryCycle</span><span class="p">([(</span><span class="mi">0</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">0</span><span class="p">),</span> <span class="p">(</span><span class="mi">1</span><span class="p">,</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">)]):</span> <span class="mi">2</span><span class="p">,</span>
<span class="gp">... </span><span class="p">}</span>
<span class="go">True</span>
</pre></div>
</div>
</dd>
</dl>
<p>Since <cite>NumberedFatgraphs</cite> are just decorated <cite>Fatgraphs</cite>, they
only differ in the way two <cite>NumberedFatgraph</cite> instances are deemed
isomorphic:</p>
<blockquote>
<div><ul class="simple">
<li>they must have isomorphic underlying graphs;</li>
<li>the numberings must match under the isomorphism map.</li>
</ul>
</div></blockquote>
<p>For example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">ug</span> <span class="o">=</span> <span class="n">Fatgraph</span><span class="p">([</span><span class="n">Vertex</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">])])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">ng1</span> <span class="o">=</span> <span class="n">NumberedFatgraph</span><span class="p">(</span><span class="n">ug</span><span class="p">,</span> <span class="n">numbering</span><span class="o">=</span><span class="p">[(</span><span class="n">BoundaryCycle</span><span class="p">([(</span><span class="mi">0</span><span class="p">,</span><span class="mi">3</span><span class="p">,</span><span class="mi">0</span><span class="p">),</span> <span class="p">(</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">)]),</span> <span class="mi">0</span><span class="p">),</span>                                                 <span class="p">(</span><span class="n">BoundaryCycle</span><span class="p">([(</span><span class="mi">0</span><span class="p">,</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">)]),</span> <span class="mi">1</span><span class="p">),</span>                                                          <span class="p">(</span><span class="n">BoundaryCycle</span><span class="p">([(</span><span class="mi">0</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">3</span><span class="p">)]),</span> <span class="mi">2</span><span class="p">)])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">ng2</span> <span class="o">=</span> <span class="n">NumberedFatgraph</span><span class="p">(</span><span class="n">ug</span><span class="p">,</span> <span class="n">numbering</span><span class="o">=</span><span class="p">[(</span><span class="n">BoundaryCycle</span><span class="p">([(</span><span class="mi">0</span><span class="p">,</span><span class="mi">3</span><span class="p">,</span><span class="mi">0</span><span class="p">),</span> <span class="p">(</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">)]),</span> <span class="mi">1</span><span class="p">),</span>                                                 <span class="p">(</span><span class="n">BoundaryCycle</span><span class="p">([(</span><span class="mi">0</span><span class="p">,</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">)]),</span> <span class="mi">0</span><span class="p">),</span>                                                          <span class="p">(</span><span class="n">BoundaryCycle</span><span class="p">([(</span><span class="mi">0</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">3</span><span class="p">)]),</span> <span class="mi">2</span><span class="p">)])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">ng1</span> <span class="o">==</span> <span class="n">ng2</span>
<span class="go">False</span>
</pre></div>
</div>
<p>Fatgraph instances equipped with a numbering are compared as
numbered graphs (that is, the isomorphism should transform the
numbering on the source graph onto the numbering of the
destination):</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">NumberedFatgraph</span><span class="o">.</span><span class="n">__eq__</span><span class="p">(</span>
<span class="gp">... </span>    <span class="n">NumberedFatgraph</span><span class="p">(</span><span class="n">Fatgraph</span><span class="p">([</span><span class="n">Vertex</span><span class="p">([</span><span class="mi">2</span><span class="p">,</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">2</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">0</span><span class="p">])]),</span> 
<span class="gp">... </span>                     <span class="n">numbering</span><span class="o">=</span><span class="p">[(</span><span class="n">BoundaryCycle</span><span class="p">([(</span><span class="mi">0</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">0</span><span class="p">),</span> <span class="p">(</span><span class="mi">1</span><span class="p">,</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">)]),</span> <span class="mi">0</span><span class="p">),</span> 
<span class="gp">... </span>                                <span class="p">(</span><span class="n">BoundaryCycle</span><span class="p">([(</span><span class="mi">0</span><span class="p">,</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">),</span> <span class="p">(</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">0</span><span class="p">)]),</span> <span class="mi">1</span><span class="p">),</span> 
<span class="gp">... </span>                                <span class="p">(</span><span class="n">BoundaryCycle</span><span class="p">([(</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">),</span> <span class="p">(</span><span class="mi">1</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">)]),</span> <span class="mi">2</span><span class="p">)</span> <span class="p">]</span> <span class="p">),</span>
<span class="gp">... </span>    <span class="n">NumberedFatgraph</span><span class="p">(</span><span class="n">Fatgraph</span><span class="p">([</span><span class="n">Vertex</span><span class="p">([</span><span class="mi">2</span><span class="p">,</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">2</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">0</span><span class="p">])]),</span> 
<span class="gp">... </span>                     <span class="n">numbering</span><span class="o">=</span><span class="p">[(</span><span class="n">BoundaryCycle</span><span class="p">([(</span><span class="mi">0</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">0</span><span class="p">),</span> <span class="p">(</span><span class="mi">1</span><span class="p">,</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">)]),</span> <span class="mi">0</span><span class="p">),</span> 
<span class="gp">... </span>                                <span class="p">(</span><span class="n">BoundaryCycle</span><span class="p">([(</span><span class="mi">0</span><span class="p">,</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">),</span> <span class="p">(</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">0</span><span class="p">)]),</span> <span class="mi">2</span><span class="p">),</span> 
<span class="gp">... </span>                                <span class="p">(</span><span class="n">BoundaryCycle</span><span class="p">([(</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">),</span> <span class="p">(</span><span class="mi">1</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">)]),</span> <span class="mi">1</span><span class="p">)</span> <span class="p">]</span> <span class="p">)</span> <span class="p">)</span>
<span class="go">True</span>

<span class="gp">&gt;&gt;&gt; </span><span class="n">NumberedFatgraph</span><span class="o">.</span><span class="n">__eq__</span><span class="p">(</span>
<span class="gp">... </span>    <span class="n">NumberedFatgraph</span><span class="p">(</span><span class="n">Fatgraph</span><span class="p">([</span><span class="n">Vertex</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">1</span><span class="p">])]),</span> 
<span class="gp">... </span>                     <span class="n">numbering</span><span class="o">=</span><span class="p">[(</span><span class="n">BoundaryCycle</span><span class="p">([(</span><span class="mi">0</span><span class="p">,</span><span class="mi">5</span><span class="p">,</span><span class="mi">0</span><span class="p">)]),</span> <span class="mi">0</span><span class="p">),</span> 
<span class="gp">... </span>                                <span class="p">(</span><span class="n">BoundaryCycle</span><span class="p">([(</span><span class="mi">0</span><span class="p">,</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">),</span> <span class="p">(</span><span class="mi">0</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">3</span><span class="p">),</span> <span class="p">(</span><span class="mi">0</span><span class="p">,</span><span class="mi">4</span><span class="p">,</span><span class="mi">5</span><span class="p">)]),</span> <span class="mi">1</span><span class="p">),</span> 
<span class="gp">... </span>                                <span class="p">(</span><span class="n">BoundaryCycle</span><span class="p">([(</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">)]),</span> <span class="mi">3</span><span class="p">),</span> 
<span class="gp">... </span>                                <span class="p">(</span><span class="n">BoundaryCycle</span><span class="p">([(</span><span class="mi">0</span><span class="p">,</span><span class="mi">3</span><span class="p">,</span><span class="mi">4</span><span class="p">)]),</span> <span class="mi">2</span><span class="p">)</span> <span class="p">]),</span>
<span class="gp">... </span>    <span class="n">NumberedFatgraph</span><span class="p">(</span> 
<span class="gp">... </span>                     <span class="n">Fatgraph</span><span class="p">([</span><span class="n">Vertex</span><span class="p">([</span><span class="mi">2</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">])]),</span> 
<span class="gp">... </span>                     <span class="n">numbering</span><span class="o">=</span><span class="p">[(</span><span class="n">BoundaryCycle</span><span class="p">([(</span><span class="mi">0</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">3</span><span class="p">)]),</span> <span class="mi">0</span><span class="p">),</span> 
<span class="gp">... </span>                                <span class="p">(</span><span class="n">BoundaryCycle</span><span class="p">([(</span><span class="mi">0</span><span class="p">,</span><span class="mi">3</span><span class="p">,</span><span class="mi">4</span><span class="p">),</span> <span class="p">(</span><span class="mi">0</span><span class="p">,</span><span class="mi">5</span><span class="p">,</span><span class="mi">0</span><span class="p">),</span> <span class="p">(</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">)]),</span> <span class="mi">3</span><span class="p">),</span> 
<span class="gp">... </span>                                <span class="p">(</span><span class="n">BoundaryCycle</span><span class="p">([(</span><span class="mi">0</span><span class="p">,</span><span class="mi">4</span><span class="p">,</span><span class="mi">5</span><span class="p">)]),</span> <span class="mi">1</span><span class="p">),</span> 
<span class="gp">... </span>                                <span class="p">(</span><span class="n">BoundaryCycle</span><span class="p">([(</span><span class="mi">0</span><span class="p">,</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">)]),</span> <span class="mi">2</span><span class="p">)</span> <span class="p">])</span> <span class="p">)</span>
<span class="go">False</span>

<span class="gp">&gt;&gt;&gt; </span><span class="n">NumberedFatgraph</span><span class="o">.</span><span class="n">__eq__</span><span class="p">(</span>
<span class="gp">... </span>    <span class="n">NumberedFatgraph</span><span class="p">(</span><span class="n">Fatgraph</span><span class="p">([</span><span class="n">Vertex</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">1</span><span class="p">])]),</span> 
<span class="gp">... </span>                     <span class="n">numbering</span><span class="o">=</span><span class="p">[(</span><span class="n">BoundaryCycle</span><span class="p">([(</span><span class="mi">0</span><span class="p">,</span><span class="mi">5</span><span class="p">,</span><span class="mi">0</span><span class="p">)]),</span> <span class="mi">0</span><span class="p">),</span> 
<span class="gp">... </span>                                <span class="p">(</span><span class="n">BoundaryCycle</span><span class="p">([(</span><span class="mi">0</span><span class="p">,</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">),</span> <span class="p">(</span><span class="mi">0</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">3</span><span class="p">),</span> <span class="p">(</span><span class="mi">0</span><span class="p">,</span><span class="mi">4</span><span class="p">,</span><span class="mi">5</span><span class="p">)]),</span> <span class="mi">1</span><span class="p">),</span>
<span class="gp">... </span>                                <span class="p">(</span><span class="n">BoundaryCycle</span><span class="p">([(</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">)]),</span> <span class="mi">3</span><span class="p">),</span> 
<span class="gp">... </span>                                <span class="p">(</span><span class="n">BoundaryCycle</span><span class="p">([(</span><span class="mi">0</span><span class="p">,</span><span class="mi">3</span><span class="p">,</span><span class="mi">4</span><span class="p">)]),</span> <span class="mi">2</span><span class="p">)</span> <span class="p">]),</span>
<span class="gp">... </span>    <span class="n">NumberedFatgraph</span><span class="p">(</span><span class="n">Fatgraph</span><span class="p">([</span><span class="n">Vertex</span><span class="p">([</span><span class="mi">2</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">])]),</span> 
<span class="gp">... </span>                     <span class="n">numbering</span><span class="o">=</span><span class="p">[(</span><span class="n">BoundaryCycle</span><span class="p">([(</span><span class="mi">0</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">3</span><span class="p">)]),</span> <span class="mi">3</span><span class="p">),</span> 
<span class="gp">... </span>                                <span class="p">(</span><span class="n">BoundaryCycle</span><span class="p">([(</span><span class="mi">0</span><span class="p">,</span><span class="mi">3</span><span class="p">,</span><span class="mi">4</span><span class="p">),</span> <span class="p">(</span><span class="mi">0</span><span class="p">,</span><span class="mi">5</span><span class="p">,</span><span class="mi">0</span><span class="p">),</span> <span class="p">(</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">)]),</span> <span class="mi">2</span><span class="p">),</span> 
<span class="gp">... </span>                                <span class="p">(</span><span class="n">BoundaryCycle</span><span class="p">([(</span><span class="mi">0</span><span class="p">,</span><span class="mi">4</span><span class="p">,</span><span class="mi">5</span><span class="p">)]),</span> <span class="mi">0</span><span class="p">),</span> 
<span class="gp">... </span>                                <span class="p">(</span><span class="n">BoundaryCycle</span><span class="p">([(</span><span class="mi">0</span><span class="p">,</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">)]),</span> <span class="mi">1</span><span class="p">)</span> <span class="p">])</span> <span class="p">)</span>
<span class="go">False</span>

<span class="gp">&gt;&gt;&gt; </span><span class="n">NumberedFatgraph</span><span class="o">.</span><span class="n">__eq__</span><span class="p">(</span>
<span class="gp">... </span>    <span class="n">NumberedFatgraph</span><span class="p">(</span><span class="n">Fatgraph</span><span class="p">([</span><span class="n">Vertex</span><span class="p">([</span><span class="mi">3</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">3</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">0</span><span class="p">])]),</span> 
<span class="gp">... </span>                     <span class="n">numbering</span><span class="o">=</span><span class="p">[(</span><span class="n">BoundaryCycle</span><span class="p">([(</span><span class="mi">0</span><span class="p">,</span><span class="mi">4</span><span class="p">,</span><span class="mi">0</span><span class="p">),</span> <span class="p">(</span><span class="mi">1</span><span class="p">,</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">)]),</span> <span class="mi">0</span><span class="p">),</span>
<span class="gp">... </span>                                <span class="p">(</span><span class="n">BoundaryCycle</span><span class="p">([(</span><span class="mi">0</span><span class="p">,</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">),</span> <span class="p">(</span><span class="mi">0</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">3</span><span class="p">),</span> <span class="p">(</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">0</span><span class="p">)]),</span> <span class="mi">1</span><span class="p">),</span>
<span class="gp">... </span>                                <span class="p">(</span><span class="n">BoundaryCycle</span><span class="p">([(</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">)]),</span> <span class="mi">2</span><span class="p">),</span>
<span class="gp">... </span>                                <span class="p">(</span><span class="n">BoundaryCycle</span><span class="p">([(</span><span class="mi">0</span><span class="p">,</span><span class="mi">3</span><span class="p">,</span><span class="mi">4</span><span class="p">),</span> <span class="p">(</span><span class="mi">1</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">)]),</span> <span class="mi">3</span><span class="p">)</span> <span class="p">]),</span>
<span class="gp">... </span>    <span class="n">NumberedFatgraph</span><span class="p">(</span><span class="n">Fatgraph</span><span class="p">([</span><span class="n">Vertex</span><span class="p">([</span><span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">1</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">2</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">])]),</span> 
<span class="gp">... </span>                     <span class="n">numbering</span><span class="o">=</span><span class="p">[(</span><span class="n">BoundaryCycle</span><span class="p">([(</span><span class="mi">0</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">0</span><span class="p">),</span> <span class="p">(</span><span class="mi">1</span><span class="p">,</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">)]),</span> <span class="mi">3</span><span class="p">),</span>
<span class="gp">... </span>                                <span class="p">(</span><span class="n">BoundaryCycle</span><span class="p">([(</span><span class="mi">0</span><span class="p">,</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">),</span> <span class="p">(</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">3</span><span class="p">),</span> <span class="p">(</span><span class="mi">1</span><span class="p">,</span><span class="mi">4</span><span class="p">,</span><span class="mi">0</span><span class="p">)]),</span> <span class="mi">1</span><span class="p">),</span>
<span class="gp">... </span>                                <span class="p">(</span><span class="n">BoundaryCycle</span><span class="p">([(</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">),</span> <span class="p">(</span><span class="mi">1</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">)]),</span> <span class="mi">0</span><span class="p">)</span> <span class="p">,</span>
<span class="gp">... </span>                                <span class="p">(</span><span class="n">BoundaryCycle</span><span class="p">([(</span><span class="mi">1</span><span class="p">,</span><span class="mi">3</span><span class="p">,</span><span class="mi">4</span><span class="p">)]),</span> <span class="mi">2</span><span class="p">)</span> <span class="p">])</span> <span class="p">)</span>
<span class="go">True</span>

<span class="gp">&gt;&gt;&gt; </span><span class="n">NumberedFatgraph</span><span class="o">.</span><span class="n">__eq__</span><span class="p">(</span>
<span class="gp">... </span>    <span class="n">NumberedFatgraph</span><span class="p">(</span><span class="n">Fatgraph</span><span class="p">([</span><span class="n">Vertex</span><span class="p">([</span><span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">1</span><span class="p">])]),</span>
<span class="gp">... </span>                     <span class="n">numbering</span><span class="o">=</span><span class="p">[(</span><span class="n">BoundaryCycle</span><span class="p">([(</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">),</span> <span class="p">(</span><span class="mi">0</span><span class="p">,</span><span class="mi">4</span><span class="p">,</span><span class="mi">5</span><span class="p">)]),</span> <span class="mi">0</span><span class="p">),</span>
<span class="gp">... </span>                                <span class="p">(</span><span class="n">BoundaryCycle</span><span class="p">([(</span><span class="mi">0</span><span class="p">,</span><span class="mi">5</span><span class="p">,</span><span class="mi">0</span><span class="p">),</span> <span class="p">(</span><span class="mi">0</span><span class="p">,</span><span class="mi">3</span><span class="p">,</span><span class="mi">4</span><span class="p">),</span> <span class="p">(</span><span class="mi">0</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">3</span><span class="p">),</span> <span class="p">(</span><span class="mi">0</span><span class="p">,</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">)]),</span> <span class="mi">1</span><span class="p">)]),</span>
<span class="gp">... </span>    <span class="n">NumberedFatgraph</span><span class="p">(</span><span class="n">Fatgraph</span><span class="p">([</span><span class="n">Vertex</span><span class="p">([</span><span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">1</span><span class="p">])]),</span>
<span class="gp">... </span>                     <span class="n">numbering</span><span class="o">=</span><span class="p">[(</span><span class="n">BoundaryCycle</span><span class="p">([(</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">),</span> <span class="p">(</span><span class="mi">0</span><span class="p">,</span><span class="mi">4</span><span class="p">,</span><span class="mi">5</span><span class="p">)]),</span> <span class="mi">1</span><span class="p">),</span>
<span class="gp">... </span>                                <span class="p">(</span><span class="n">BoundaryCycle</span><span class="p">([(</span><span class="mi">0</span><span class="p">,</span><span class="mi">5</span><span class="p">,</span><span class="mi">0</span><span class="p">),</span> <span class="p">(</span><span class="mi">0</span><span class="p">,</span><span class="mi">3</span><span class="p">,</span><span class="mi">4</span><span class="p">),</span> <span class="p">(</span><span class="mi">0</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">3</span><span class="p">),</span> <span class="p">(</span><span class="mi">0</span><span class="p">,</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">)]),</span> <span class="mi">0</span><span class="p">)])</span> <span class="p">)</span>
<span class="go">False</span>
</pre></div>
</div>
<dl class="method">
<dt id="fatghol.graph_homology.NumberedFatgraph.contract">
<tt class="descname">contract</tt><big>(</big><em>obj</em>, <em>edgeno</em><big>)</big><a class="reference internal" href="_modules/fatghol/graph_homology.html#NumberedFatgraph.contract"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.graph_homology.NumberedFatgraph.contract" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a new <cite>NumberedFatgraph</cite> instance, obtained by
contracting the specified edge.</p>
<p>Examples:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">g0</span> <span class="o">=</span> <span class="n">NumberedFatgraph</span><span class="p">(</span><span class="n">Fatgraph</span><span class="p">([</span><span class="n">Vertex</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">1</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">2</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">])]),</span>
<span class="gp">... </span>                      <span class="n">numbering</span><span class="o">=</span><span class="p">{</span><span class="n">BoundaryCycle</span><span class="p">([(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">),</span> <span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">0</span><span class="p">),</span>
<span class="gp">... </span>                                                <span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">),</span> <span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">)]):</span> <span class="mi">0</span><span class="p">,</span>
<span class="gp">... </span>                                 <span class="n">BoundaryCycle</span><span class="p">([(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">)]):</span> <span class="mi">1</span><span class="p">,</span>
<span class="gp">... </span>                                 <span class="n">BoundaryCycle</span><span class="p">([(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">0</span><span class="p">)]):</span> <span class="mi">2</span><span class="p">})</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">g0</span><span class="o">.</span><span class="n">contract</span><span class="p">(</span><span class="mi">2</span><span class="p">)</span>
<span class="go">NumberedFatgraph(Fatgraph([Vertex([1, 1, 0, 0])]),</span>
<span class="go">                 numbering={BoundaryCycle([(0, 3, 0), (0, 1, 2)]): 0,</span>
<span class="go">                            BoundaryCycle([(0, 2, 3)]): 1,</span>
<span class="go">                            BoundaryCycle([(0, 0, 1)]): 2})</span>

<span class="gp">&gt;&gt;&gt; </span><span class="n">g1</span> <span class="o">=</span> <span class="n">NumberedFatgraph</span><span class="p">(</span><span class="n">Fatgraph</span><span class="p">([</span><span class="n">Vertex</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">2</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">2</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">5</span><span class="p">]),</span>
<span class="gp">... </span>                                <span class="n">Vertex</span><span class="p">([</span><span class="mi">0</span><span class="p">,</span> <span class="mi">4</span><span class="p">,</span> <span class="mi">3</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">4</span><span class="p">,</span> <span class="mi">5</span><span class="p">,</span> <span class="mi">3</span><span class="p">])]),</span>
<span class="gp">... </span>                      <span class="n">numbering</span><span class="o">=</span><span class="p">{</span><span class="n">BoundaryCycle</span><span class="p">([(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">0</span><span class="p">),</span> <span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">),</span> <span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">),</span>
<span class="gp">... </span>                                                <span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">),</span> <span class="p">(</span><span class="mi">2</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">),</span> <span class="p">(</span><span class="mi">3</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">),</span>
<span class="gp">... </span>                                                <span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">0</span><span class="p">),</span> <span class="p">(</span><span class="mi">2</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">0</span><span class="p">),</span> <span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">),</span>
<span class="gp">... </span>                                                                      <span class="p">(</span><span class="mi">3</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">)]):</span> <span class="mi">0</span><span class="p">,</span>
<span class="gp">... </span>                                 <span class="n">BoundaryCycle</span><span class="p">([(</span><span class="mi">3</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">0</span><span class="p">),</span> <span class="p">(</span><span class="mi">2</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">)]):</span> <span class="mi">1</span><span class="p">})</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">g1</span><span class="o">.</span><span class="n">contract</span><span class="p">(</span><span class="mi">0</span><span class="p">)</span>
<span class="go">NumberedFatgraph(Fatgraph([Vertex([1, 0, 3, 2]), Vertex([1, 0, 4]), Vertex([3, 4, 2])]),</span>
<span class="go">                 numbering={BoundaryCycle([(2, 1, 2), (0, 1, 2), (0, 0, 1), (1, 1, 2),</span>
<span class="go">                                           (0, 3, 0), (2, 0, 1), (1, 2, 0), (1, 0, 1)]): 0,</span>
<span class="go">                            BoundaryCycle([(0, 2, 3), (2, 2, 0)]): 1})</span>
</pre></div>
</div>
</dd></dl>

<dl class="method">
<dt id="fatghol.graph_homology.NumberedFatgraph.isomorphisms">
<tt class="descname">isomorphisms</tt><big>(</big><em>G1</em>, <em>G2</em><big>)</big><a class="reference internal" href="_modules/fatghol/graph_homology.html#NumberedFatgraph.isomorphisms"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.graph_homology.NumberedFatgraph.isomorphisms" title="Permalink to this definition">¶</a></dt>
<dd><p>Iterate over isomorphisms from <cite>G1</cite> to <cite>G2</cite>.</p>
<p>See <cite>Fatgraph.isomrphisms</cite> for a discussion of the
representation of isomorphisms and example usage.</p>
<p>A concrete example taken from <a href="#id9"><span class="problematic" id="id10">`M_{1,4}`:latex:</span></a></p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">g1</span> <span class="o">=</span> <span class="n">NumberedFatgraph</span><span class="p">(</span>
<span class="gp">... </span>        <span class="n">Fatgraph</span><span class="p">([</span><span class="n">Vertex</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">2</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">2</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">5</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">0</span><span class="p">,</span> <span class="mi">4</span><span class="p">,</span> <span class="mi">3</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">8</span><span class="p">,</span> <span class="mi">5</span><span class="p">,</span> <span class="mi">6</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">3</span><span class="p">,</span> <span class="mi">6</span><span class="p">,</span> <span class="mi">7</span><span class="p">,</span> <span class="mi">7</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">8</span><span class="p">,</span> <span class="mi">4</span><span class="p">,</span> <span class="mi">9</span><span class="p">,</span> <span class="mi">9</span><span class="p">])]),</span>
<span class="gp">... </span>        <span class="n">numbering</span><span class="o">=</span><span class="p">{</span>
<span class="gp">... </span>            <span class="n">BoundaryCycle</span><span class="p">([(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">),</span> <span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">),</span> <span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">0</span><span class="p">),</span> <span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">),</span> <span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">),</span> <span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">0</span><span class="p">),</span> <span class="p">(</span><span class="mi">2</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">),</span> <span class="p">(</span><span class="mi">2</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">0</span><span class="p">),</span> <span class="p">(</span><span class="mi">3</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">),</span> <span class="p">(</span><span class="mi">3</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">),</span> <span class="p">(</span><span class="mi">4</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">),</span> <span class="p">(</span><span class="mi">4</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">0</span><span class="p">),</span> <span class="p">(</span><span class="mi">5</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">),</span> <span class="p">(</span><span class="mi">5</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">0</span><span class="p">)]):</span><span class="mi">0</span><span class="p">,</span>
<span class="gp">... </span>            <span class="n">BoundaryCycle</span><span class="p">([(</span><span class="mi">2</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">),</span> <span class="p">(</span><span class="mi">3</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">0</span><span class="p">),</span> <span class="p">(</span><span class="mi">4</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">),</span> <span class="p">(</span><span class="mi">5</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">)]):</span><span class="mi">1</span><span class="p">,</span>
<span class="gp">... </span>            <span class="n">BoundaryCycle</span><span class="p">([(</span><span class="mi">4</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">)]):</span><span class="mi">2</span><span class="p">,</span>
<span class="gp">... </span>            <span class="n">BoundaryCycle</span><span class="p">([(</span><span class="mi">5</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">)]):</span><span class="mi">3</span><span class="p">,</span>
<span class="gp">... </span>      <span class="p">})</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">g2</span> <span class="o">=</span> <span class="n">NumberedFatgraph</span><span class="p">(</span>
<span class="gp">... </span>        <span class="n">Fatgraph</span><span class="p">([</span><span class="n">Vertex</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">5</span><span class="p">,</span> <span class="mi">6</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">2</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">5</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">8</span><span class="p">,</span> <span class="mi">4</span><span class="p">,</span> <span class="mi">3</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">7</span><span class="p">,</span> <span class="mi">7</span><span class="p">,</span> <span class="mi">6</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">4</span><span class="p">,</span> <span class="mi">8</span><span class="p">,</span> <span class="mi">9</span><span class="p">,</span> <span class="mi">9</span><span class="p">])]),</span>
<span class="gp">... </span>        <span class="n">numbering</span><span class="o">=</span><span class="p">{</span>
<span class="gp">... </span>            <span class="n">BoundaryCycle</span><span class="p">([(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">),</span> <span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">),</span> <span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">),</span> <span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">0</span><span class="p">),</span> <span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">),</span> <span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">),</span> <span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">0</span><span class="p">),</span> <span class="p">(</span><span class="mi">2</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">),</span> <span class="p">(</span><span class="mi">2</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">),</span> <span class="p">(</span><span class="mi">2</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">0</span><span class="p">),</span> <span class="p">(</span><span class="mi">3</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">),</span> <span class="p">(</span><span class="mi">3</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">0</span><span class="p">),</span> <span class="p">(</span><span class="mi">4</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">),</span> <span class="p">(</span><span class="mi">4</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">0</span><span class="p">),</span> <span class="p">(</span><span class="mi">5</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">),</span> <span class="p">(</span><span class="mi">5</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">0</span><span class="p">)]):</span><span class="mi">0</span><span class="p">,</span>
<span class="gp">... </span>            <span class="n">BoundaryCycle</span><span class="p">([(</span><span class="mi">3</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">),</span> <span class="p">(</span><span class="mi">5</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">)]):</span><span class="mi">1</span><span class="p">,</span>
<span class="gp">... </span>            <span class="n">BoundaryCycle</span><span class="p">([(</span><span class="mi">4</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">)]):</span><span class="mi">2</span><span class="p">,</span>
<span class="gp">... </span>            <span class="n">BoundaryCycle</span><span class="p">([(</span><span class="mi">5</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">)]):</span><span class="mi">3</span><span class="p">,</span>
<span class="gp">... </span>     <span class="p">})</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">len</span><span class="p">(</span><span class="nb">list</span><span class="p">(</span><span class="n">NumberedFatgraph</span><span class="o">.</span><span class="n">isomorphisms</span><span class="p">(</span><span class="n">g1</span><span class="p">,</span> <span class="n">g2</span><span class="p">)))</span>
<span class="go">0</span>
</pre></div>
</div>
</dd></dl>

</dd></dl>

<dl class="class">
<dt id="fatghol.graph_homology.NumberedFatgraphPool">
<em class="property">class </em><tt class="descclassname">fatghol.graph_homology.</tt><tt class="descname">NumberedFatgraphPool</tt><big>(</big><em>graph</em><big>)</big><a class="reference internal" href="_modules/fatghol/graph_homology.html#NumberedFatgraphPool"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.graph_homology.NumberedFatgraphPool" title="Permalink to this definition">¶</a></dt>
<dd><p>An immutable virtual collection of <cite>NumberedFatgraph`s.
Items are all distinct (up to isomorphism) decorations of a
`Fatgraph</cite> instance <cite>graph</cite> with a numbering of the boundary
cycles.</p>
<p>Implements object lookup by index and iteration over the whole list.</p>
<p>Examples:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">ug1</span> <span class="o">=</span> <span class="n">Fatgraph</span><span class="p">([</span><span class="n">Vertex</span><span class="p">([</span><span class="mi">2</span><span class="p">,</span><span class="mi">0</span><span class="p">,</span><span class="mi">0</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">2</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">1</span><span class="p">])])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">p</span> <span class="o">=</span> <span class="n">NumberedFatgraphPool</span><span class="p">(</span><span class="n">ug1</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">len</span><span class="p">(</span><span class="n">p</span><span class="p">)</span>
<span class="go">3</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">for</span> <span class="n">g</span> <span class="ow">in</span> <span class="n">p</span><span class="p">:</span> <span class="k">print</span> <span class="n">g</span>
<span class="go">NumberedFatgraph(Fatgraph([Vertex([2, 0, 0]), Vertex([2, 1, 1])]),</span>
<span class="go">                 numbering={BoundaryCycle([(0, 2, 0), (1, 2, 0), (0, 0, 1), (1, 0, 1)]): 0,</span>
<span class="go">                            BoundaryCycle([(0, 1, 2)]): 1,</span>
<span class="go">                            BoundaryCycle([(1, 1, 2)]): 2})</span>
<span class="go">NumberedFatgraph(Fatgraph([Vertex([2, 0, 0]), Vertex([2, 1, 1])]),</span>
<span class="go">                 numbering={BoundaryCycle([(0, 1, 2)]): 0,</span>
<span class="go">                            BoundaryCycle([(0, 2, 0), (1, 2, 0), (0, 0, 1), (1, 0, 1)]): 1,</span>
<span class="go">                            BoundaryCycle([(1, 1, 2)]): 2})</span>
<span class="go">NumberedFatgraph(Fatgraph([Vertex([2, 0, 0]), Vertex([2, 1, 1])]),</span>
<span class="go">                 numbering={BoundaryCycle([(0, 1, 2)]): 0,</span>
<span class="go">                            BoundaryCycle([(1, 1, 2)]): 1,</span>
<span class="go">                            BoundaryCycle([(0, 2, 0), (1, 2, 0), (0, 0, 1), (1, 0, 1)]): 2})</span>
</pre></div>
</div>
<p>Note that, when only one numbering out of many possible ones is
returned because of isomorphism, the returned numbering may not be
the trivial one (it is infact the first permutation of 0..n
returned by <cite>InplacePermutationIterator</cite>):</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">ug2</span> <span class="o">=</span> <span class="n">Fatgraph</span><span class="p">([</span><span class="n">Vertex</span><span class="p">([</span><span class="mi">2</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">0</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">2</span><span class="p">,</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">])])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">for</span> <span class="n">g</span> <span class="ow">in</span> <span class="n">NumberedFatgraphPool</span><span class="p">(</span><span class="n">ug2</span><span class="p">):</span> <span class="k">print</span> <span class="n">g</span>
<span class="go">NumberedFatgraph(Fatgraph([Vertex([2, 1, 0]), Vertex([2, 0, 1])]),</span>
<span class="go">                  numbering={BoundaryCycle([(1, 2, 0), (0, 0, 1)]): 0,</span>
<span class="go">                             BoundaryCycle([(0, 1, 2), (1, 1, 2)]): 1,</span>
<span class="go">                             BoundaryCycle([(0, 2, 0), (1, 0, 1)]): 2})</span>
</pre></div>
</div>
<p>When the graph has only one boundary component, there is only one
possible numbering, which is actually returned:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">ug3</span> <span class="o">=</span> <span class="n">Fatgraph</span><span class="p">([</span><span class="n">Vertex</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">0</span><span class="p">])])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">for</span> <span class="n">g</span> <span class="ow">in</span> <span class="n">NumberedFatgraphPool</span><span class="p">(</span><span class="n">ug3</span><span class="p">):</span> <span class="k">print</span> <span class="n">g</span>
<span class="go">NumberedFatgraph(Fatgraph([Vertex([1, 0, 1, 0])]),</span>
<span class="go">                  numbering={BoundaryCycle([(0, 3, 0), (0, 2, 3),</span>
<span class="go">                                            (0, 1, 2), (0, 0, 1)]): 0})</span>
</pre></div>
</div>
<p>Index lookup returns a <cite>NumberedFatgraph</cite> instance, produced
on-the-fly:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">ug4</span> <span class="o">=</span> <span class="n">Fatgraph</span><span class="p">([</span><span class="n">Vertex</span><span class="p">([</span><span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">2</span><span class="p">])])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">pool</span> <span class="o">=</span> <span class="n">NumberedFatgraphPool</span><span class="p">(</span><span class="n">ug4</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">pool</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span>
<span class="go">NumberedFatgraph(Fatgraph([Vertex([0, 1, 0, 1, 2, 2])]),</span>
<span class="go">                 numbering={BoundaryCycle([(0, 2, 3), (0, 3, 4),</span>
<span class="go">                                           (0, 1, 2), (0, 0, 1), (0, 5, 0)]): 0,</span>
<span class="go">                            BoundaryCycle([(0, 4, 5)]): 1})</span>
</pre></div>
</div>
<dl class="method">
<dt id="fatghol.graph_homology.NumberedFatgraphPool.facets">
<tt class="descname">facets</tt><big>(</big><em>edge</em>, <em>other</em><big>)</big><a class="reference internal" href="_modules/fatghol/graph_homology.html#NumberedFatgraphPool.facets"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.graph_homology.NumberedFatgraphPool.facets" title="Permalink to this definition">¶</a></dt>
<dd><p>Iterate over facets obtained by contracting <cite>edge</cite> and
projecting onto <cite>other</cite>.</p>
<dl class="docutils">
<dt>Each returned item is a triple <cite>(j, k, s)</cite>, where:</dt>
<dd><ul class="first last simple">
<li><cite>j</cite> is the index of a <cite>NumberedFatgraph</cite> in <cite>self</cite>;</li>
<li><cite>k</cite> is the index of a <cite>NumberedFatgraph</cite> in <cite>other</cite>;</li>
<li><cite>s</cite> is the sign by which <cite>self[j].contract(edge)</cite> projects onto <cite>other[k]</cite>.</li>
</ul>
</dd>
</dl>
<p>Only triples for which <cite>s != 0</cite> are returned.</p>
<p>Examples:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">p0</span> <span class="o">=</span> <span class="n">NumberedFatgraphPool</span><span class="p">(</span><span class="n">Fatgraph</span><span class="p">([</span><span class="n">Vertex</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">0</span><span class="p">]),</span> <span class="n">Vertex</span><span class="p">([</span><span class="mi">3</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">2</span><span class="p">])]))</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">p1</span> <span class="o">=</span> <span class="n">NumberedFatgraphPool</span><span class="p">(</span><span class="n">Fatgraph</span><span class="p">([</span><span class="n">Vertex</span><span class="p">([</span><span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">2</span><span class="p">])]))</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">list</span><span class="p">(</span><span class="n">NumberedFatgraphPool</span><span class="o">.</span><span class="n">facets</span><span class="p">(</span><span class="n">p0</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="n">p1</span><span class="p">))</span>
<span class="go">[(0, 0, 1), (1, 1, 1)]</span>
</pre></div>
</div>
</dd></dl>

</dd></dl>

</div>
<div class="section" id="module-fatghol.valences">
<span id="fatghol-valences"></span><h3><cite>fatghol.valences</cite><a class="headerlink" href="#module-fatghol.valences" title="Permalink to this headline">¶</a></h3>
<p>Functions related to valences of ribbon graphs.</p>
<dl class="function">
<dt id="fatghol.valences.vertex_valences_for_given_g_and_n">
<tt class="descclassname">fatghol.valences.</tt><tt class="descname">vertex_valences_for_given_g_and_n</tt><big>(</big><em>g</em>, <em>n</em><big>)</big><a class="reference internal" href="_modules/fatghol/valences.html#vertex_valences_for_given_g_and_n"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.valences.vertex_valences_for_given_g_and_n" title="Permalink to this definition">¶</a></dt>
<dd><p>Return all possible valences of fatgraphs appearing in the
<cite>(g,n)</cite> complex.</p>
<p>The returned partitions are sorted in ascending order.</p>
<dl class="docutils">
<dt>Examples::</dt>
<dd><div class="first last highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">vertex_valences_for_given_g_and_n</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span><span class="mi">3</span><span class="p">)</span>
<span class="go">[(3, 3), (4,)]</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">vertex_valences_for_given_g_and_n</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span><span class="mi">1</span><span class="p">)</span>
<span class="go">[(3, 3), (4,)]</span>
</pre></div>
</div>
</dd>
</dl>
</dd></dl>

</div>
</div>
<div class="section" id="utility-modules">
<h2>Utility modules<a class="headerlink" href="#utility-modules" title="Permalink to this headline">¶</a></h2>
<p>These are support modules, used by the core FatGHoL modules.  They are
more general in nature and most code from these modules could be
packaged separately and re-used in other projects.</p>
<div class="section" id="module-fatghol.aggregate">
<span id="fatghol-aggregate"></span><h3><cite>fatghol.aggregate</cite><a class="headerlink" href="#module-fatghol.aggregate" title="Permalink to this headline">¶</a></h3>
<p>The <cite>AggregateList</cite> class.</p>
<dl class="class">
<dt id="fatghol.aggregate.AggregateList">
<em class="property">class </em><tt class="descclassname">fatghol.aggregate.</tt><tt class="descname">AggregateList</tt><big>(</big><em>*seqs</em><big>)</big><a class="reference internal" href="_modules/fatghol/aggregate.html#AggregateList"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.aggregate.AggregateList" title="Permalink to this definition">¶</a></dt>
<dd><p>Act on a set of lists as if they were concatenated together.</p>
<p>The aggregate list acts as a collective: the length is the sum of
all the components&#8217; length, iteration over the composite list
reveals all the components members in the order the components
were added.  References to elements of the aggregate list are
routed to the component lists, and iteration over the aggregate
list returns the elements of the component lists (in the order the
components were added to the aggregate):</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">a1</span> <span class="o">=</span> <span class="p">[</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">]</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">a2</span> <span class="o">=</span> <span class="p">[</span><span class="mi">3</span><span class="p">,</span> <span class="mi">4</span><span class="p">]</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">a</span> <span class="o">=</span> <span class="n">AggregateList</span><span class="p">(</span><span class="n">a1</span><span class="p">,</span> <span class="n">a2</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">len</span><span class="p">(</span><span class="n">a</span><span class="p">)</span>
<span class="go">5</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">a</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span>
<span class="go">1</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">a</span><span class="p">[</span><span class="mi">4</span><span class="p">]</span>
<span class="go">4</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">a</span><span class="p">[</span><span class="mi">4</span><span class="p">]</span> <span class="o">=</span> <span class="mi">77</span>
<span class="gp">&gt;&gt;&gt; </span><span class="mi">77</span> <span class="ow">in</span> <span class="n">a</span>
<span class="go">True</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">list</span><span class="p">(</span><span class="n">a</span><span class="p">)</span>
<span class="go">[0, 1, 2, 3, 77]</span>
</pre></div>
</div>
<p>Operations are routed to the appropriate component list: e.g.,
<cite>append</cite> appends to the last list in the group.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">a</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="mi">5</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">a2</span>
<span class="go">[3, 77, 5]</span>
</pre></div>
</div>
<dl class="docutils">
<dt><em>Note:</em> Currently not implemented:</dt>
<dd><ul class="first last simple">
<li>remove()</li>
<li>pop()</li>
<li>count()</li>
<li>sort()</li>
<li>reverse()</li>
<li>All slicing operations.</li>
</ul>
</dd>
</dl>
<dl class="method">
<dt id="fatghol.aggregate.AggregateList.aggregate">
<tt class="descname">aggregate</tt><big>(</big><em>*seqs</em><big>)</big><a class="reference internal" href="_modules/fatghol/aggregate.html#AggregateList.aggregate"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.aggregate.AggregateList.aggregate" title="Permalink to this definition">¶</a></dt>
<dd><p>Append each sequence in <cite>seqs</cite> to the aggregated list.</p>
<p>Example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">a</span> <span class="o">=</span> <span class="n">AggregateList</span><span class="p">([</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">a</span><span class="o">.</span><span class="n">aggregate</span><span class="p">([</span><span class="mi">3</span><span class="p">,</span><span class="mi">4</span><span class="p">],[</span><span class="mi">5</span><span class="p">,</span><span class="mi">6</span><span class="p">])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">list</span><span class="p">(</span><span class="n">a</span><span class="p">)</span>
<span class="go">[0, 1, 2, 3, 4, 5, 6]</span>
</pre></div>
</div>
</dd></dl>

<dl class="method">
<dt id="fatghol.aggregate.AggregateList.aggregate1">
<tt class="descname">aggregate1</tt><big>(</big><em>seq</em><big>)</big><a class="reference internal" href="_modules/fatghol/aggregate.html#AggregateList.aggregate1"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.aggregate.AggregateList.aggregate1" title="Permalink to this definition">¶</a></dt>
<dd><p>Append sequence <cite>seq</cite> to the aggregate list.</p>
<p>Example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">a</span> <span class="o">=</span> <span class="n">AggregateList</span><span class="p">([</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">a</span><span class="o">.</span><span class="n">aggregate</span><span class="p">([</span><span class="mi">3</span><span class="p">,</span><span class="mi">4</span><span class="p">])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">a</span><span class="o">.</span><span class="n">aggregate</span><span class="p">([</span><span class="mi">5</span><span class="p">,</span><span class="mi">6</span><span class="p">])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">list</span><span class="p">(</span><span class="n">a</span><span class="p">)</span>
<span class="go">[0, 1, 2, 3, 4, 5, 6]</span>
</pre></div>
</div>
</dd></dl>

<dl class="method">
<dt id="fatghol.aggregate.AggregateList.append">
<tt class="descname">append</tt><big>(</big><em>item</em><big>)</big><a class="reference internal" href="_modules/fatghol/aggregate.html#AggregateList.append"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.aggregate.AggregateList.append" title="Permalink to this definition">¶</a></dt>
<dd><p>Append <cite>item</cite> to the last component.</p>
</dd></dl>

<dl class="method">
<dt id="fatghol.aggregate.AggregateList.extend">
<tt class="descname">extend</tt><big>(</big><em>seq</em><big>)</big><a class="reference internal" href="_modules/fatghol/aggregate.html#AggregateList.extend"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.aggregate.AggregateList.extend" title="Permalink to this definition">¶</a></dt>
<dd><p>Extend the last component with <cite>seq</cite>.</p>
</dd></dl>

<dl class="method">
<dt id="fatghol.aggregate.AggregateList.index">
<tt class="descname">index</tt><big>(</big><em>value</em>, <em>start=0</em><big>)</big><a class="reference internal" href="_modules/fatghol/aggregate.html#AggregateList.index"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.aggregate.AggregateList.index" title="Permalink to this definition">¶</a></dt>
<dd><p>Return index of the first element equal to <cite>value</cite>.</p>
</dd></dl>

</dd></dl>

</div>
<div class="section" id="module-fatghol.cache">
<span id="fatghol-cache"></span><h3><cite>fatghol.cache</cite><a class="headerlink" href="#module-fatghol.cache" title="Permalink to this headline">¶</a></h3>
<p>Utilities for caching computation results.</p>
<dl class="class">
<dt id="fatghol.cache.Caching">
<em class="property">class </em><tt class="descclassname">fatghol.cache.</tt><tt class="descname">Caching</tt><a class="reference internal" href="_modules/fatghol/cache.html#Caching"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.cache.Caching" title="Permalink to this definition">¶</a></dt>
<dd><p>Instances of this class provide an interface for use by caches
based on a <cite>dict</cite> subclass.</p>
</dd></dl>

<dl class="function">
<dt id="fatghol.cache.fcache">
<tt class="descclassname">fatghol.cache.</tt><tt class="descname">fcache</tt><big>(</big><em>func</em><big>)</big><a class="reference internal" href="_modules/fatghol/cache.html#fcache"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.cache.fcache" title="Permalink to this definition">¶</a></dt>
<dd><p>Cache result of a generic function.</p>
<p>This decorator can cache results of calls <cite>func(*args)</cite>.</p>
<p>CAVEATS:</p>
<ol class="arabic simple">
<li>The whole argument tuple is cached, so any object referenced</li>
</ol>
<blockquote>
<div>there will <em>not</em> be garbage collected!</div></blockquote>
<ol class="arabic simple" start="2">
<li>No keyword arguments are allowed in the cached function.</li>
</ol>
</dd></dl>

<dl class="function">
<dt id="fatghol.cache.ocache0">
<tt class="descclassname">fatghol.cache.</tt><tt class="descname">ocache0</tt><big>(</big><em>func</em><big>)</big><a class="reference internal" href="_modules/fatghol/cache.html#ocache0"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.cache.ocache0" title="Permalink to this definition">¶</a></dt>
<dd><p>Cache result of a nullary object method.</p>
<p>This decorator can cache results of calls <cite>obj.method()</cite>. The
result cache is held in the object itself; therefore, to cache
result from methods of objects using a &#8216;__slots__&#8217; declaration, a
&#8216;_cache&#8217; slot must be present and writable.</p>
</dd></dl>

<dl class="function">
<dt id="fatghol.cache.ocache_contract">
<tt class="descclassname">fatghol.cache.</tt><tt class="descname">ocache_contract</tt><big>(</big><em>func</em><big>)</big><a class="reference internal" href="_modules/fatghol/cache.html#ocache_contract"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.cache.ocache_contract" title="Permalink to this definition">¶</a></dt>
<dd><p>Cache result of the <cite>Fatgraph.contract</cite> method.</p>
<p>Only a weak reference to the method&#8217;s result is held, so the cache
entry is automatically freed when the result Fatgraph goes out of
scope.</p>
<p>Results of calls are cached in the <cite>Fatgraph</cite> instance on which
the method is called, so they are automatically dropped when that
object is collected.</p>
</dd></dl>

<dl class="function">
<dt id="fatghol.cache.ocache_eq">
<tt class="descclassname">fatghol.cache.</tt><tt class="descname">ocache_eq</tt><big>(</big><em>func</em><big>)</big><a class="reference internal" href="_modules/fatghol/cache.html#ocache_eq"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.cache.ocache_eq" title="Permalink to this definition">¶</a></dt>
<dd><p>Cache result of the 2-ary symmetric <cite>Fatgraph.__eq__</cite> method.</p>
<p>Results of calls are cached in the <cite>Fatgraph</cite> instance on which
the method is called, <em>and</em> (simmetrically) in the <cite>Fatgraph</cite> to
which that is compared to.</p>
<p>Only a weak reference to the compared-to graph is held, so the
cache entry is automatically freed when the compared-to Fatgraph
goes out of scope.</p>
</dd></dl>

<dl class="function">
<dt id="fatghol.cache.ocache_isomorphisms">
<tt class="descclassname">fatghol.cache.</tt><tt class="descname">ocache_isomorphisms</tt><big>(</big><em>func</em><big>)</big><a class="reference internal" href="_modules/fatghol/cache.html#ocache_isomorphisms"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.cache.ocache_isomorphisms" title="Permalink to this definition">¶</a></dt>
<dd><p>Cache results of <cite>isomorphisms(g1,g2)</cite> methods, which return an
iterator/generator.</p>
<p>Iterator results cannot be cached like any other object, because
they need to return the same set of values each time the
generating function is invoked.</p>
<p>Results of calls are cached in the <cite>Fatgraph</cite> instance on which
the method is called, so they are automatically dropped when that
object is collected.</p>
<p>Only a weak reference to the target Fatgraph is held, so the cache
entry is automatically freed when it goes out of scope.</p>
</dd></dl>

</div>
<div class="section" id="module-fatghol.combinatorics">
<span id="fatghol-combinatorics"></span><h3><cite>fatghol.combinatorics</cite><a class="headerlink" href="#module-fatghol.combinatorics" title="Permalink to this headline">¶</a></h3>
<p>Common combinatorics constructions.</p>
<dl class="class">
<dt id="fatghol.combinatorics.FixedLengthPartitionIterator">
<em class="property">class </em><tt class="descclassname">fatghol.combinatorics.</tt><tt class="descname">FixedLengthPartitionIterator</tt><big>(</big><em>N</em>, <em>K</em>, <em>min_=1</em>, <em>max_=None</em><big>)</big><a class="reference internal" href="_modules/fatghol/combinatorics.html#FixedLengthPartitionIterator"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.combinatorics.FixedLengthPartitionIterator" title="Permalink to this definition">¶</a></dt>
<dd><p>Iterate over partitions of integer <cite>N</cite> into <em>exactly</em> <cite>K</cite>
positive integers.</p>
<p>Each returned partition is a list of positive integers in
descending order, such that their sum is <cite>N</cite>.</p>
<p>Arguments <cite>min_</cite> and <cite>max_</cite> bound the values in each partition.</p>
<dl class="docutils">
<dt>Examples::</dt>
<dd><div class="first last highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="nb">list</span><span class="p">(</span><span class="n">FixedLengthPartitionIterator</span><span class="p">(</span><span class="mi">3</span><span class="p">,</span><span class="mi">1</span><span class="p">))</span>
<span class="go">[(3,)]</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">list</span><span class="p">(</span><span class="n">FixedLengthPartitionIterator</span><span class="p">(</span><span class="mi">3</span><span class="p">,</span><span class="mi">2</span><span class="p">))</span>
<span class="go">[(2, 1)]</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">list</span><span class="p">(</span><span class="n">FixedLengthPartitionIterator</span><span class="p">(</span><span class="mi">3</span><span class="p">,</span><span class="mi">3</span><span class="p">))</span>
<span class="go">[(1, 1, 1)]</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">list</span><span class="p">(</span><span class="n">FixedLengthPartitionIterator</span><span class="p">(</span><span class="mi">6</span><span class="p">,</span><span class="mi">2</span><span class="p">))</span>
<span class="go">[(5, 1), (4, 2), (3, 3)]</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">list</span><span class="p">(</span><span class="n">FixedLengthPartitionIterator</span><span class="p">(</span><span class="mi">8</span><span class="p">,</span><span class="mi">3</span><span class="p">))</span>
<span class="go">[(6, 1, 1), (5, 2, 1), (4, 3, 1), (4, 2, 2), (3, 3, 2)]</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">list</span><span class="p">(</span><span class="n">FixedLengthPartitionIterator</span><span class="p">(</span><span class="mi">8</span><span class="p">,</span><span class="mi">4</span><span class="p">,</span><span class="mi">2</span><span class="p">))</span>
<span class="go">[(2, 2, 2, 2)]</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">list</span><span class="p">(</span><span class="n">FixedLengthPartitionIterator</span><span class="p">(</span><span class="mi">8</span><span class="p">,</span><span class="mi">3</span><span class="p">,</span><span class="mi">2</span><span class="p">))</span>
<span class="go">[(4, 2, 2), (3, 3, 2)]</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">list</span><span class="p">(</span><span class="n">FixedLengthPartitionIterator</span><span class="p">(</span><span class="mi">8</span><span class="p">,</span><span class="mi">3</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">3</span><span class="p">))</span>
<span class="go">[(3, 3, 2)]      </span>
</pre></div>
</div>
</dd>
</dl>
</dd></dl>

<dl class="class">
<dt id="fatghol.combinatorics.InplacePermutationIterator">
<em class="property">class </em><tt class="descclassname">fatghol.combinatorics.</tt><tt class="descname">InplacePermutationIterator</tt><big>(</big><em>seq</em>, <em>start=0</em>, <em>end=None</em><big>)</big><a class="reference internal" href="_modules/fatghol/combinatorics.html#InplacePermutationIterator"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.combinatorics.InplacePermutationIterator" title="Permalink to this definition">¶</a></dt>
<dd><p>Iterate (destructively) over all permutations of a given sequence.</p>
<p>The given sequence <cite>seq</cite> is altered as new permutations are
requested through the <cite>next()</cite> method.  In order to use the
returned value after subsequent calls to
<cite>InplacePermutationIterator.next()</cite>, you must make a copy of it.</p>
<dl class="docutils">
<dt>The code is a port of the C++ STL one, explained in:</dt>
<dd><a class="reference external" href="http://marknelson.us/2002/03/01/next-permutation">http://marknelson.us/2002/03/01/next-permutation</a></dd>
</dl>
<p>The number of permutations of a list of length <cite>n</cite> equals <cite>n!</cite>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="k">for</span> <span class="n">n</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="mi">6</span><span class="p">):</span>
<span class="gp">... </span>  <span class="k">print</span> <span class="nb">len</span><span class="p">(</span><span class="nb">list</span><span class="p">(</span><span class="n">InplacePermutationIterator</span><span class="p">(</span><span class="nb">range</span><span class="p">(</span><span class="n">n</span><span class="o">+</span><span class="mi">1</span><span class="p">))))</span>
<span class="go">1</span>
<span class="go">2</span>
<span class="go">6</span>
<span class="go">24</span>
<span class="go">120</span>
<span class="go">720</span>
</pre></div>
</div>
<dl class="docutils">
<dt>Examples::</dt>
<dd><div class="first last highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="p">[</span> <span class="n">x</span><span class="p">[:]</span> <span class="k">for</span> <span class="n">x</span> <span class="ow">in</span> <span class="n">InplacePermutationIterator</span><span class="p">([</span><span class="mi">0</span><span class="p">])</span> <span class="p">]</span>
<span class="go">[[0]]</span>
<span class="gp">&gt;&gt;&gt; </span><span class="p">[</span> <span class="n">x</span><span class="p">[:]</span> <span class="k">for</span> <span class="n">x</span> <span class="ow">in</span> <span class="n">InplacePermutationIterator</span><span class="p">([</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">])</span> <span class="p">]</span>
<span class="go">[[1, 0], [0, 1]]</span>
<span class="gp">&gt;&gt;&gt; </span><span class="p">[</span> <span class="n">x</span><span class="p">[:]</span> <span class="k">for</span> <span class="n">x</span> <span class="ow">in</span> <span class="n">InplacePermutationIterator</span><span class="p">([</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">])]</span>
<span class="go">[[0, 2, 1], [1, 0, 2], [1, 2, 0], [2, 0, 1], [2, 1, 0], [0, 1, 2]]</span>
</pre></div>
</div>
</dd>
</dl>
<dl class="method">
<dt id="fatghol.combinatorics.InplacePermutationIterator.next">
<tt class="descname">next</tt><big>(</big><big>)</big><a class="reference internal" href="_modules/fatghol/combinatorics.html#InplacePermutationIterator.next"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.combinatorics.InplacePermutationIterator.next" title="Permalink to this definition">¶</a></dt>
<dd><p>Return next permutation of initially given <cite>sequence</cite>.</p>
</dd></dl>

</dd></dl>

<dl class="class">
<dt id="fatghol.combinatorics.OrderedSetPartitionsIterator">
<em class="property">class </em><tt class="descclassname">fatghol.combinatorics.</tt><tt class="descname">OrderedSetPartitionsIterator</tt><big>(</big><em>sizes</em>, <em>items=None</em><big>)</big><a class="reference internal" href="_modules/fatghol/combinatorics.html#OrderedSetPartitionsIterator"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.combinatorics.OrderedSetPartitionsIterator" title="Permalink to this definition">¶</a></dt>
<dd><p>Iterate over all (ordered) partitions of a set with prescribed block sizes.</p>
<p>Instanciating an <cite>OrderedSetPartitionsIterator</cite> object requires
two arguments: second argument <cite>set</cite> is a list of items to be
partitioned into blocks, whose sizes are prescribed by first
argument <cite>sizes</cite>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="nb">tuple</span><span class="p">(</span><span class="n">OrderedSetPartitionsIterator</span><span class="p">([</span><span class="mi">2</span><span class="p">,</span><span class="mi">3</span><span class="p">],</span> <span class="p">[</span><span class="s">&#39;a&#39;</span><span class="p">,</span><span class="s">&#39;b&#39;</span><span class="p">,</span><span class="s">&#39;c&#39;</span><span class="p">,</span><span class="s">&#39;d&#39;</span><span class="p">,</span><span class="s">&#39;e&#39;</span><span class="p">]))</span>
<span class="go">([[&#39;a&#39;, &#39;b&#39;], [&#39;c&#39;, &#39;d&#39;, &#39;e&#39;]],</span>
<span class="go"> [[&#39;a&#39;, &#39;c&#39;], [&#39;b&#39;, &#39;d&#39;, &#39;e&#39;]],</span>
<span class="go"> [[&#39;a&#39;, &#39;d&#39;], [&#39;b&#39;, &#39;c&#39;, &#39;e&#39;]],</span>
<span class="go"> [[&#39;a&#39;, &#39;e&#39;], [&#39;b&#39;, &#39;c&#39;, &#39;d&#39;]],</span>
<span class="go"> [[&#39;b&#39;, &#39;c&#39;], [&#39;a&#39;, &#39;d&#39;, &#39;e&#39;]],</span>
<span class="go"> [[&#39;b&#39;, &#39;d&#39;], [&#39;a&#39;, &#39;c&#39;, &#39;e&#39;]],</span>
<span class="go"> [[&#39;b&#39;, &#39;e&#39;], [&#39;a&#39;, &#39;c&#39;, &#39;d&#39;]],</span>
<span class="go"> [[&#39;c&#39;, &#39;d&#39;], [&#39;a&#39;, &#39;b&#39;, &#39;e&#39;]],</span>
<span class="go"> [[&#39;c&#39;, &#39;e&#39;], [&#39;a&#39;, &#39;b&#39;, &#39;d&#39;]],</span>
<span class="go"> [[&#39;d&#39;, &#39;e&#39;], [&#39;a&#39;, &#39;b&#39;, &#39;c&#39;]])</span>
</pre></div>
</div>
<p>Each returned partition is a list whose items are -in turn- list
of the sizes prescribed in the <cite>sizes</cite> argument, in the order
given.</p>
<p>If the set to be partitioned is omitted, then the integer range
<cite>[0, 1, ..., N=sum(sizes)]</cite> is used:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="nb">tuple</span><span class="p">(</span><span class="n">OrderedSetPartitionsIterator</span><span class="p">([</span><span class="mi">2</span><span class="p">,</span><span class="mi">1</span><span class="p">]))</span>
<span class="go">([[0, 1], [2]],</span>
<span class="go"> [[0, 2], [1]],</span>
<span class="go"> [[1, 2], [0]])</span>
</pre></div>
</div>
<p>If the size of the given <cite>set</cite> does not match the total size of
the partition blocks, an exception is raised:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">OrderedSetPartitionsIterator</span><span class="p">([</span><span class="mi">2</span><span class="p">,</span><span class="mi">2</span><span class="p">],</span> <span class="p">[</span><span class="s">&#39;a&#39;</span><span class="p">,</span><span class="s">&#39;b&#39;</span><span class="p">,</span><span class="s">&#39;c&#39;</span><span class="p">])</span>
<span class="gt">Traceback (most recent call last):</span>
  <span class="c">...</span>
<span class="gr">AssertionError</span>: <span class="n">Sum of partition lengths is not equal to set size.</span>
</pre></div>
</div>
<p><strong>Note:</strong> The order of parts <em>is</em> significant: thus, if the
<cite>sizes</cite> list prescribes two or more blocks of equal size, then,
for each partition, one gotten from it by permuting the same-size
blocks is returned as a distinct partition:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="nb">tuple</span><span class="p">(</span><span class="n">OrderedSetPartitionsIterator</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span><span class="mi">1</span><span class="p">]))</span>
<span class="go">([[0], [1]], [[1], [0]])</span>
</pre></div>
</div>
<p>This is not what you would expect in a set-theoretical partition
enumerator.</p>
<p>This is a Python port of the David Landgren&#8217;s <cite>Set::Partition</cite>
CPAN module, which see for an explanation of how the algorithm
works.</p>
</dd></dl>

<dl class="function">
<dt id="fatghol.combinatorics.PartitionIterator">
<tt class="descclassname">fatghol.combinatorics.</tt><tt class="descname">PartitionIterator</tt><big>(</big><em>N</em>, <em>K</em>, <em>min_=1</em>, <em>max_=None</em><big>)</big><a class="reference internal" href="_modules/fatghol/combinatorics.html#PartitionIterator"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.combinatorics.PartitionIterator" title="Permalink to this definition">¶</a></dt>
<dd><p>Iterate over partitions of integer <cite>N</cite> into <em>at most</em> <cite>K</cite>
positive integers.</p>
<p>Each returned partition is a list of positive integers in
descending order, such that their sum is <cite>N</cite>.</p>
<p>Optional arguments <cite>min_</cite> and <cite>max_</cite> bound the values in each
partition.</p>
<dl class="docutils">
<dt>Examples::</dt>
<dd><div class="first last highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="nb">list</span><span class="p">(</span><span class="n">PartitionIterator</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span><span class="mi">1</span><span class="p">))</span>
<span class="go">[(2,)]</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">list</span><span class="p">(</span><span class="n">PartitionIterator</span><span class="p">(</span><span class="mi">3</span><span class="p">,</span><span class="mi">3</span><span class="p">))</span>
<span class="go">[(3,), (2, 1), (1, 1, 1)]</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">list</span><span class="p">(</span><span class="n">PartitionIterator</span><span class="p">(</span><span class="mi">8</span><span class="p">,</span><span class="mi">3</span><span class="p">,</span><span class="mi">2</span><span class="p">))</span>
<span class="go">[(8,), (6, 2), (5, 3), (4, 4), (4, 2, 2), (3, 3, 2)]</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">list</span><span class="p">(</span><span class="n">PartitionIterator</span><span class="p">(</span><span class="mi">8</span><span class="p">,</span><span class="mi">3</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">3</span><span class="p">))</span>
<span class="go">[(3, 3, 2)]      </span>
</pre></div>
</div>
</dd>
</dl>
</dd></dl>

<dl class="class">
<dt id="fatghol.combinatorics.Permutation">
<em class="property">class </em><tt class="descclassname">fatghol.combinatorics.</tt><tt class="descname">Permutation</tt><big>(</big><em>initial=</em><span class="optional">[</span><span class="optional">]</span><big>)</big><a class="reference internal" href="_modules/fatghol/combinatorics.html#Permutation"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.combinatorics.Permutation" title="Permalink to this definition">¶</a></dt>
<dd><p>A permutation of a finite set.</p>
<p>Provides methods to incrementally construct the map by extending
an existing map with new source-&gt;destination pairs; the extension
will fail if any new source-&gt;destination assignment contrasts with
what is already there.</p>
<dl class="method">
<dt id="fatghol.combinatorics.Permutation.extend">
<tt class="descname">extend</tt><big>(</big><em>srcs</em>, <em>dsts</em><big>)</big><a class="reference internal" href="_modules/fatghol/combinatorics.html#Permutation.extend"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.combinatorics.Permutation.extend" title="Permalink to this definition">¶</a></dt>
<dd><p>Return <cite>True</cite> if the mapping can be extended by mapping
elements of <cite>srcs</cite> to corresponding elements of <cite>dsts</cite>.
Return <cite>False</cite> if any of the new mappings conflicts with an
already established one.</p>
<dl class="docutils">
<dt>Examples::</dt>
<dd><div class="first last highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">m</span><span class="o">=</span><span class="n">Permutation</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">m</span><span class="o">.</span><span class="n">extend</span><span class="p">([</span><span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">],</span> <span class="p">[</span><span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">])</span>
<span class="go">True</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">m</span><span class="o">.</span><span class="n">extend</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">],</span> <span class="p">[</span><span class="mi">0</span><span class="p">,</span> <span class="mi">2</span><span class="p">])</span>
<span class="go">False</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">m</span><span class="o">.</span><span class="n">extend</span><span class="p">([</span><span class="mi">2</span><span class="p">],</span> <span class="p">[</span><span class="mi">2</span><span class="p">])</span>
<span class="go">True</span>
</pre></div>
</div>
</dd>
</dl>
</dd></dl>

<dl class="method">
<dt id="fatghol.combinatorics.Permutation.find">
<tt class="descname">find</tt><big>(</big><em>value</em><big>)</big><a class="reference internal" href="_modules/fatghol/combinatorics.html#Permutation.find"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.combinatorics.Permutation.find" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the key that maps to <cite>value</cite>, or <cite>None</cite> if <cite>value</cite> is
not in this <cite>Permutation</cite> domain.</p>
<p>Examples:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">m</span> <span class="o">=</span> <span class="n">Permutation</span><span class="p">({</span><span class="mi">0</span><span class="p">:</span><span class="mi">2</span><span class="p">,</span> <span class="mi">1</span><span class="p">:</span><span class="mi">0</span><span class="p">,</span> <span class="mi">2</span><span class="p">:</span><span class="mi">1</span><span class="p">})</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">m</span><span class="o">.</span><span class="n">find</span><span class="p">(</span><span class="mi">0</span><span class="p">)</span>
<span class="go">1</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">m</span><span class="o">.</span><span class="n">find</span><span class="p">(</span><span class="mi">3</span><span class="p">)</span> <span class="ow">is</span> <span class="bp">None</span>
<span class="go">True</span>
</pre></div>
</div>
</dd></dl>

<dl class="method">
<dt id="fatghol.combinatorics.Permutation.inverse">
<tt class="descname">inverse</tt><big>(</big><big>)</big><a class="reference internal" href="_modules/fatghol/combinatorics.html#Permutation.inverse"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.combinatorics.Permutation.inverse" title="Permalink to this definition">¶</a></dt>
<dd><p>Construct and return the inverse permutation.</p>
<p>Examples:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">p</span> <span class="o">=</span> <span class="n">Permutation</span><span class="p">({</span><span class="mi">0</span><span class="p">:</span><span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">:</span><span class="mi">2</span><span class="p">,</span> <span class="mi">2</span><span class="p">:</span><span class="mi">0</span><span class="p">})</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">p</span><span class="o">.</span><span class="n">inverse</span><span class="p">()</span>
<span class="go">{0: 2, 1: 0, 2: 1}</span>

<span class="gp">&gt;&gt;&gt; </span><span class="n">p</span> <span class="o">=</span> <span class="n">Permutation</span><span class="p">(</span><span class="nb">enumerate</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span> <span class="mi">0</span><span class="p">]))</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">p</span><span class="o">.</span><span class="n">inverse</span><span class="p">()</span> <span class="o">==</span> <span class="n">p</span>
<span class="go">True</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">p</span><span class="o">.</span><span class="n">inverse</span><span class="p">()</span> <span class="ow">is</span> <span class="n">p</span>
<span class="go">False</span>
</pre></div>
</div>
</dd></dl>

<dl class="method">
<dt id="fatghol.combinatorics.Permutation.is_identity">
<tt class="descname">is_identity</tt><big>(</big><big>)</big><a class="reference internal" href="_modules/fatghol/combinatorics.html#Permutation.is_identity"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.combinatorics.Permutation.is_identity" title="Permalink to this definition">¶</a></dt>
<dd><p>Return <cite>True</cite> if permutation leaves all items fixed.</p>
</dd></dl>

<dl class="method">
<dt id="fatghol.combinatorics.Permutation.itranslate">
<tt class="descname">itranslate</tt><big>(</big><em>iterable</em><big>)</big><a class="reference internal" href="_modules/fatghol/combinatorics.html#Permutation.itranslate"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.combinatorics.Permutation.itranslate" title="Permalink to this definition">¶</a></dt>
<dd><p>Create an iterator returning items from <cite>iterable</cite>,
permuted according to this <cite>Permutation</cite> instance.</p>
<p>For this to work, items in <cite>iterable</cite> must be integers in the
range from 0 up to (and excluding) the length of this
permutation.  Otherwise a <cite>KeyError</cite> is raised.</p>
<p>Examples:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">s</span> <span class="o">=</span> <span class="p">[</span><span class="mi">1</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">2</span><span class="p">]</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">p</span> <span class="o">=</span> <span class="n">Permutation</span><span class="p">(</span><span class="nb">enumerate</span><span class="p">([</span><span class="mi">0</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">1</span><span class="p">]))</span> <span class="c"># map 0-&gt;0, 1-&gt;2, 2-&gt;1</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">list</span><span class="p">(</span><span class="n">p</span><span class="o">.</span><span class="n">itranslate</span><span class="p">(</span><span class="n">s</span><span class="p">))</span>
<span class="go">[2, 0, 1]</span>
</pre></div>
</div>
</dd></dl>

<dl class="method">
<dt id="fatghol.combinatorics.Permutation.ltranslate">
<tt class="descname">ltranslate</tt><big>(</big><em>iterable</em><big>)</big><a class="reference internal" href="_modules/fatghol/combinatorics.html#Permutation.ltranslate"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.combinatorics.Permutation.ltranslate" title="Permalink to this definition">¶</a></dt>
<dd><p>Retutn list of items from <cite>iterable</cite>, permuted according to
this <cite>Permutation</cite> instance.</p>
<p>For this to work, items in <cite>iterable</cite> must be integers in the
range from 0 up to (and excluding) the length of this
permutation.  Otherwise a <cite>KeyError</cite> is raised.</p>
<p>Examples:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">s</span> <span class="o">=</span> <span class="p">[</span><span class="mi">1</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">2</span><span class="p">]</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">p</span> <span class="o">=</span> <span class="n">Permutation</span><span class="p">(</span><span class="nb">enumerate</span><span class="p">([</span><span class="mi">0</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">1</span><span class="p">]))</span> <span class="c"># map 0-&gt;0, 1-&gt;2, 2-&gt;1</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">p</span><span class="o">.</span><span class="n">ltranslate</span><span class="p">(</span><span class="n">s</span><span class="p">)</span>
<span class="go">[2, 0, 1]</span>
</pre></div>
</div>
</dd></dl>

<dl class="method">
<dt id="fatghol.combinatorics.Permutation.rearranged">
<tt class="descname">rearranged</tt><big>(</big><em>seq</em><big>)</big><a class="reference internal" href="_modules/fatghol/combinatorics.html#Permutation.rearranged"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.combinatorics.Permutation.rearranged" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a new list containing the items in <cite>seq</cite>, rearranged
according to this permutation.</p>
<p>Examples:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">s</span> <span class="o">=</span> <span class="p">[</span><span class="s">&#39;a&#39;</span><span class="p">,</span><span class="s">&#39;b&#39;</span><span class="p">,</span><span class="s">&#39;c&#39;</span><span class="p">]</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">p</span> <span class="o">=</span> <span class="n">Permutation</span><span class="p">(</span><span class="nb">enumerate</span><span class="p">([</span><span class="mi">2</span><span class="p">,</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">]))</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">p</span><span class="o">.</span><span class="n">rearranged</span><span class="p">(</span><span class="n">s</span><span class="p">)</span>
<span class="go">[&#39;c&#39;, &#39;a&#39;, &#39;b&#39;]</span>
</pre></div>
</div>
</dd></dl>

<dl class="method">
<dt id="fatghol.combinatorics.Permutation.sign">
<tt class="descname">sign</tt><big>(</big><big>)</big><a class="reference internal" href="_modules/fatghol/combinatorics.html#Permutation.sign"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.combinatorics.Permutation.sign" title="Permalink to this definition">¶</a></dt>
<dd><p>Return sign of this <cite>Permutation</cite>.</p>
<p>Examples:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">Permutation</span><span class="p">(</span><span class="nb">enumerate</span><span class="p">([</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">]))</span><span class="o">.</span><span class="n">sign</span><span class="p">()</span>
<span class="go">1</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">Permutation</span><span class="p">(</span><span class="nb">enumerate</span><span class="p">([</span><span class="mi">0</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">1</span><span class="p">]))</span><span class="o">.</span><span class="n">sign</span><span class="p">()</span>
<span class="go">-1</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">Permutation</span><span class="p">(</span><span class="nb">enumerate</span><span class="p">([</span><span class="mi">2</span><span class="p">,</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">]))</span><span class="o">.</span><span class="n">sign</span><span class="p">()</span>
<span class="go">1</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">Permutation</span><span class="p">(</span><span class="nb">enumerate</span><span class="p">([</span><span class="mi">3</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">]))</span><span class="o">.</span><span class="n">sign</span><span class="p">()</span>
<span class="go">-1</span>
</pre></div>
</div>
<p>The trivial permutations mapping a single element into
itself and the empty permutation are assigned sign +1:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">Permutation</span><span class="p">(</span><span class="nb">enumerate</span><span class="p">([</span><span class="mi">0</span><span class="p">]))</span><span class="o">.</span><span class="n">sign</span><span class="p">()</span>
<span class="go">1</span>

<span class="gp">&gt;&gt;&gt; </span><span class="n">Permutation</span><span class="p">()</span><span class="o">.</span><span class="n">sign</span><span class="p">()</span>
<span class="go">1</span>
</pre></div>
</div>
<p>This is an adaptation of the <cite>perm_sign</cite> code by John Burkardt
(see it among the collection at
<a class="reference external" href="http://orion.math.iastate.edu/burkardt/f_src/subset/subset.f90">http://orion.math.iastate.edu/burkardt/f_src/subset/subset.f90</a>
or <a class="reference external" href="http://www.scs.fsu.edu/~burkardt/math2071/perm_sign.m">http://www.scs.fsu.edu/~burkardt/math2071/perm_sign.m</a> ); it
computes the sign by counting the number of interchanges
required to change the given permutation into the identity
one.</p>
</dd></dl>

<dl class="method">
<dt id="fatghol.combinatorics.Permutation.translate">
<tt class="descname">translate</tt><big>(</big><em>seq</em><big>)</big><a class="reference internal" href="_modules/fatghol/combinatorics.html#Permutation.translate"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.combinatorics.Permutation.translate" title="Permalink to this definition">¶</a></dt>
<dd><p>Alter <cite>seq</cite>, applying this permutation to the value of its items.
Return modified sequence.</p>
<p>For this to work, items in <cite>seq</cite> must be integers in the range
from 0 up to (and excluding) the length of this permutation.
Otherwise a <cite>KeyError</cite> is raised.</p>
<p>Examples:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">s</span> <span class="o">=</span> <span class="p">[</span><span class="mi">1</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">2</span><span class="p">]</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">p</span> <span class="o">=</span> <span class="n">Permutation</span><span class="p">(</span><span class="nb">enumerate</span><span class="p">([</span><span class="mi">0</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">1</span><span class="p">]))</span> <span class="c"># map 0-&gt;0, 1-&gt;2, 2-&gt;1</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">p</span><span class="o">.</span><span class="n">translate</span><span class="p">(</span><span class="n">s</span><span class="p">)</span>
<span class="go">[2, 0, 1]</span>
</pre></div>
</div>
</dd></dl>

<dl class="method">
<dt id="fatghol.combinatorics.Permutation.update">
<tt class="descname">update</tt><big>(</big><em>mappings</em><big>)</big><a class="reference internal" href="_modules/fatghol/combinatorics.html#Permutation.update"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.combinatorics.Permutation.update" title="Permalink to this definition">¶</a></dt>
<dd><p>Return <cite>True</cite> if the mapping can be extended by mapping each
key of <cite>mappings</cite> to the corresponding value.  Return <cite>False</cite>
if any of the new mappings conflicts with an already
established one.</p>
</dd></dl>

</dd></dl>

<dl class="class">
<dt id="fatghol.combinatorics.PermutationIterator">
<em class="property">class </em><tt class="descclassname">fatghol.combinatorics.</tt><tt class="descname">PermutationIterator</tt><big>(</big><em>seq</em>, <em>initial=0</em><big>)</big><a class="reference internal" href="_modules/fatghol/combinatorics.html#PermutationIterator"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.combinatorics.PermutationIterator" title="Permalink to this definition">¶</a></dt>
<dd><p>Iterate over all permutations of a given sequence.</p>
<dl class="docutils">
<dt>The code is a port of the one described in Wikipedia at:</dt>
<dd><a class="reference external" href="http://en.wikipedia.org/wiki/Permutation#Algorithm_to_generate_permutations">http://en.wikipedia.org/wiki/Permutation#Algorithm_to_generate_permutations</a></dd>
<dt>The permutations are returned in no particular order::</dt>
<dd><div class="first highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">p</span> <span class="o">=</span> <span class="n">PermutationIterator</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">3</span><span class="p">])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">p</span><span class="o">.</span><span class="n">next</span><span class="p">()</span>
<span class="go">(3, 1, 2)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">p</span><span class="o">.</span><span class="n">next</span><span class="p">()</span>
<span class="go">(3, 2, 1)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">p</span><span class="o">.</span><span class="n">next</span><span class="p">()</span>
<span class="go">(2, 3, 1)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">p</span><span class="o">.</span><span class="n">next</span><span class="p">()</span>
<span class="go">(1, 3, 2)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">p</span><span class="o">.</span><span class="n">next</span><span class="p">()</span>
<span class="go">(2, 1, 3)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">p</span><span class="o">.</span><span class="n">next</span><span class="p">()</span>
<span class="go">(1, 2, 3)</span>
</pre></div>
</div>
<div class="last highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="k">for</span> <span class="n">n</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="mi">6</span><span class="p">):</span>
<span class="gp">... </span>  <span class="k">print</span> <span class="nb">len</span><span class="p">(</span><span class="nb">set</span><span class="p">(</span><span class="nb">tuple</span><span class="p">(</span><span class="n">x</span><span class="p">)</span> <span class="k">for</span> <span class="n">x</span> <span class="ow">in</span> <span class="n">PermutationIterator</span><span class="p">(</span><span class="nb">range</span><span class="p">(</span><span class="n">n</span><span class="o">+</span><span class="mi">1</span><span class="p">))))</span>
<span class="go">1</span>
<span class="go">2</span>
<span class="go">6</span>
<span class="go">24</span>
<span class="go">120</span>
<span class="go">720</span>
</pre></div>
</div>
</dd>
</dl>
<dl class="method">
<dt id="fatghol.combinatorics.PermutationIterator.next">
<tt class="descname">next</tt><big>(</big><big>)</big><a class="reference internal" href="_modules/fatghol/combinatorics.html#PermutationIterator.next"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.combinatorics.PermutationIterator.next" title="Permalink to this definition">¶</a></dt>
<dd><p>Return next permutation of initially given <cite>sequence</cite>.</p>
</dd></dl>

</dd></dl>

<dl class="class">
<dt id="fatghol.combinatorics.PermutationList">
<em class="property">class </em><tt class="descclassname">fatghol.combinatorics.</tt><tt class="descname">PermutationList</tt><big>(</big><em>order</em><big>)</big><a class="reference internal" href="_modules/fatghol/combinatorics.html#PermutationList"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.combinatorics.PermutationList" title="Permalink to this definition">¶</a></dt>
<dd><p>Simulate a (read-only) list of all permutations of a prescribed order.</p>
<p>The list is ordered lexicographically; at position <cite>0</cite> and <cite>n!</cite>
are the identity permutation and the order-reversal permutation,
respectively.</p>
<dl class="docutils">
<dt>The code is a port of the one described in Wikipedia at:</dt>
<dd><a class="reference external" href="http://en.wikipedia.org/wiki/Permutation#Algorithm_to_generate_permutations">http://en.wikipedia.org/wiki/Permutation#Algorithm_to_generate_permutations</a></dd>
<dt>Examples::</dt>
<dd><div class="first highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">ps</span> <span class="o">=</span> <span class="n">PermutationList</span><span class="p">(</span><span class="mi">3</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">ps</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span>
<span class="go">(0, 1, 2)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">ps</span><span class="p">[</span><span class="mi">5</span><span class="p">]</span>
<span class="go">(2, 1, 0)</span>
</pre></div>
</div>
<div class="last highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="k">for</span> <span class="n">n</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="mi">6</span><span class="p">):</span>
<span class="gp">... </span>  <span class="k">print</span> <span class="nb">len</span><span class="p">(</span><span class="nb">set</span><span class="p">(</span><span class="nb">tuple</span><span class="p">(</span><span class="n">x</span><span class="p">)</span> <span class="k">for</span> <span class="n">x</span> <span class="ow">in</span> <span class="n">PermutationList</span><span class="p">(</span><span class="n">n</span><span class="o">+</span><span class="mi">1</span><span class="p">)))</span>
<span class="go">1</span>
<span class="go">2</span>
<span class="go">6</span>
<span class="go">24</span>
<span class="go">120</span>
<span class="go">720</span>
</pre></div>
</div>
</dd>
</dl>
</dd></dl>

<dl class="class">
<dt id="fatghol.combinatorics.SetProductIterator_">
<em class="property">class </em><tt class="descclassname">fatghol.combinatorics.</tt><tt class="descname">SetProductIterator_</tt><big>(</big><em>*factors</em><big>)</big><a class="reference internal" href="_modules/fatghol/combinatorics.html#SetProductIterator_"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.combinatorics.SetProductIterator_" title="Permalink to this definition">¶</a></dt>
<dd><p>Iterate over all elements in a cartesian product.</p>
<p>Argument <cite>factors</cite> is a sequence, all whose items are sequences
themselves: the returned iterator will return -upon each
successive invocation- a tuple <cite>(t_1, t_2, ..., t_n)</cite> where <cite>t_k</cite>
is an item in the <cite>k</cite>-th sequence.</p>
<dl class="docutils">
<dt>Examples::</dt>
<dd><div class="first last highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="nb">list</span><span class="p">(</span><span class="n">SetProductIterator_</span><span class="p">())</span>
<span class="go">[()]</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">list</span><span class="p">(</span><span class="n">SetProductIterator_</span><span class="p">([</span><span class="mi">1</span><span class="p">]))</span>
<span class="go">[(1,)]</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">list</span><span class="p">(</span><span class="n">SetProductIterator_</span><span class="p">([</span><span class="mi">1</span><span class="p">],[</span><span class="mi">1</span><span class="p">]))</span>
<span class="go">[(1, 1)]</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">list</span><span class="p">(</span><span class="n">SetProductIterator_</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">],[]))</span>
<span class="go">[()]</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">list</span><span class="p">(</span><span class="n">SetProductIterator_</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">],[</span><span class="mi">1</span><span class="p">]))</span>
<span class="go">[(1, 1), (2, 1)]</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">list</span><span class="p">(</span><span class="n">SetProductIterator_</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">],[</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">]))</span>
<span class="go">[(1, 1), (2, 1), (1, 2), (2, 2)]</span>
</pre></div>
</div>
</dd>
</dl>
</dd></dl>

<dl class="function">
<dt id="fatghol.combinatorics.bernoulli">
<tt class="descclassname">fatghol.combinatorics.</tt><tt class="descname">bernoulli</tt><big>(</big><em>n</em><big>)</big><a class="reference internal" href="_modules/fatghol/combinatorics.html#bernoulli"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.combinatorics.bernoulli" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the <cite>n</cite>-th Bernoulli number.</p>
<p>The convention used here is that B(0)=1 and that B(n) is the n-th
term of the Taylor-McLaurin series of the generating function <cite>x /
(exp x - 1)</cite>.</p>
<p>Computation uses a recursive formula which is unsuitable for
anything but small values of <cite>n</cite>.</p>
<p>The returned object is a <cite>fractions.Fraction</cite>, even in the case of
integer Bernoulli numbers:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">bernoulli</span><span class="p">(</span><span class="mi">0</span><span class="p">)</span>
<span class="go">Fraction(1, 1)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">bernoulli</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>
<span class="go">Fraction(-1, 2)</span>
</pre></div>
</div>
<p>Examples:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="k">for</span> <span class="n">n</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="mi">19</span><span class="p">):</span> <span class="k">print</span> <span class="n">bernoulli</span><span class="p">(</span><span class="n">n</span><span class="p">)</span>
<span class="go">1</span>
<span class="go">-1/2</span>
<span class="go">1/6</span>
<span class="go">0</span>
<span class="go">-1/30</span>
<span class="go">0</span>
<span class="go">1/42</span>
<span class="go">0</span>
<span class="go">-1/30</span>
<span class="go">0</span>
<span class="go">5/66</span>
<span class="go">0</span>
<span class="go">-691/2730</span>
<span class="go">0</span>
<span class="go">7/6</span>
<span class="go">0</span>
<span class="go">-3617/510</span>
<span class="go">0</span>
<span class="go">43867/798</span>
</pre></div>
</div>
</dd></dl>

<dl class="function">
<dt id="fatghol.combinatorics.choose">
<tt class="descclassname">fatghol.combinatorics.</tt><tt class="descname">choose</tt><big>(</big><em>*args</em><big>)</big><a class="reference internal" href="_modules/fatghol/combinatorics.html#choose"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.combinatorics.choose" title="Permalink to this definition">¶</a></dt>
<dd><p>Return <cite>choose{n}{k}</cite>.</p>
<p>The returned object is a <cite>fractions.Fraction</cite>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">choose</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span><span class="mi">0</span><span class="p">)</span>
<span class="go">Fraction(1, 1)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">choose</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span><span class="mi">1</span><span class="p">)</span>
<span class="go">Fraction(2, 1)</span>
</pre></div>
</div>
<p>Examples:</p>
<div class="highlight-python"><pre># Pascal's triangle
&gt;&gt;&gt; for n in range(5): 
...   print str.join(" ", [("%d" % choose(n,k)) for k in range(n+1)])
1
1 1
1 2 1
1 3 3 1
1 4 6 4 1</pre>
</div>
</dd></dl>

<dl class="function">
<dt id="fatghol.combinatorics.factorial">
<tt class="descclassname">fatghol.combinatorics.</tt><tt class="descname">factorial</tt><big>(</big><em>*args</em><big>)</big><a class="reference internal" href="_modules/fatghol/combinatorics.html#factorial"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.combinatorics.factorial" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the factorial of <cite>n</cite>.</p>
<p>Examples:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="k">for</span> <span class="n">n</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="mi">7</span><span class="p">):</span> <span class="k">print</span> <span class="n">factorial</span><span class="p">(</span><span class="n">n</span><span class="p">)</span>
<span class="go">1</span>
<span class="go">1</span>
<span class="go">2</span>
<span class="go">6</span>
<span class="go">24</span>
<span class="go">120</span>
<span class="go">720</span>
</pre></div>
</div>
<p>Argument <cite>n</cite> can also be a negative number:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">factorial</span><span class="p">(</span><span class="o">-</span><span class="mi">5</span><span class="p">)</span>
<span class="go">-120</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">factorial</span><span class="p">(</span><span class="o">-</span><span class="mi">2</span><span class="p">)</span>
<span class="go">2</span>
</pre></div>
</div>
</dd></dl>

<dl class="function">
<dt id="fatghol.combinatorics.minus_one_exp">
<tt class="descclassname">fatghol.combinatorics.</tt><tt class="descname">minus_one_exp</tt><big>(</big><em>m</em><big>)</big><a class="reference internal" href="_modules/fatghol/combinatorics.html#minus_one_exp"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.combinatorics.minus_one_exp" title="Permalink to this definition">¶</a></dt>
<dd><p>Return (-1) to the power <cite>m</cite>.</p>
</dd></dl>

</div>
<div class="section" id="module-fatghol.const">
<span id="fatghol-const"></span><h3><cite>fatghol.const</cite><a class="headerlink" href="#module-fatghol.const" title="Permalink to this headline">¶</a></h3>
<p>Compute well-known invariants of <cite>M_{g,n}</cite>.</p>
<dl class="function">
<dt id="fatghol.const.euler_characteristics">
<tt class="descclassname">fatghol.const.</tt><tt class="descname">euler_characteristics</tt><big>(</big><em>g</em>, <em>n</em><big>)</big><a class="reference internal" href="_modules/fatghol/const.html#euler_characteristics"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.const.euler_characteristics" title="Permalink to this definition">¶</a></dt>
<dd><p>Return Euler characteristics of <cite>M_{g,n}</cite>.</p>
<p>The Euler characteristics is computed according to formulas and
tables found in:
* Bini-Gaiffi-Polito, arXiv:math/9806048, p.3
* Bini-Harer, arXiv:math/0506083, p. 10</p>
</dd></dl>

<dl class="function">
<dt id="fatghol.const.orbifold_euler_characteristics">
<tt class="descclassname">fatghol.const.</tt><tt class="descname">orbifold_euler_characteristics</tt><big>(</big><em>g</em>, <em>n</em><big>)</big><a class="reference internal" href="_modules/fatghol/const.html#orbifold_euler_characteristics"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.const.orbifold_euler_characteristics" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the orbifold/virtual Euler characteristics of <cite>M_{g,n}</cite>,
computed according to Harer-Zagier.</p>
</dd></dl>

</div>
<div class="section" id="module-fatghol.cyclicseq">
<span id="fatghol-cyclicseq"></span><h3><cite>fatghol.cyclicseq</cite><a class="headerlink" href="#module-fatghol.cyclicseq" title="Permalink to this headline">¶</a></h3>
<p>Cyclic sequence factories.</p>
<p>Defines a type factory <cite>CyclicSequence</cite>, which can be applied to any
sequence-like type to produce a&#8221;cyclic&#8221; variant, that is, indices wrap
around: if <cite>a</cite> is such a cyclic sequence, then <cite>a[i] == a[i + len(a)]</cite>
for any index <cite>i</cite>.  For example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">clist</span> <span class="o">=</span> <span class="n">CyclicSequence</span><span class="p">(</span><span class="nb">list</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">a</span> <span class="o">=</span> <span class="n">clist</span><span class="p">([</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">3</span><span class="p">])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">len</span><span class="p">(</span><span class="n">a</span><span class="p">)</span>
<span class="go">4</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">a</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span> <span class="o">==</span> <span class="n">a</span><span class="p">[</span><span class="mi">5</span><span class="p">]</span>
<span class="go">True</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">a</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span> <span class="o">==</span> <span class="n">a</span><span class="p">[</span><span class="mi">9</span><span class="p">]</span>
<span class="go">True</span>
</pre></div>
</div>
<p>More generally, <cite>a[i] == a[j]</cite> if <cite>i = j mod len(a)</cite>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">a</span><span class="p">[</span><span class="mi">5</span><span class="p">]</span> <span class="c"># == a[2]</span>
<span class="go">1</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">a</span><span class="p">[</span><span class="o">-</span><span class="mi">7</span><span class="p">]</span> <span class="c"># == a[2]</span>
<span class="go">1</span>
</pre></div>
</div>
<p>By default, this module exports cyclic variants of the standard
<cite>tuple</cite> and <cite>list</cite> sequences:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">CyclicTuple</span> <span class="o">=</span> <span class="n">CyclicSequence</span><span class="p">(</span><span class="nb">tuple</span><span class="p">)</span>
<span class="n">CyclicList</span> <span class="o">=</span> <span class="n">CyclicSequence</span><span class="p">(</span><span class="nb">list</span><span class="p">)</span>
</pre></div>
</div>
<p><cite>CyclicSequence</cite> assumes that an instance of the base (non-cyclic)
type can be instanciated by passing to it only one argument, namely,
the initialization sequence.  (This is how the standard sequence types
<cite>list</cite> and <cite>tuple</cite> behave.)  For types needing a more complex
construction, a factory function must be passed as second argument:
the factory function accepts the initialization sequence and returns
an instance of the base type.  For example, this is how one can define
cyclic variants of the sequences provided by the <cite>array</cite> module:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="c"># cyclic versions of sequences in the `array` module</span>
<span class="kn">from</span> <span class="nn">array</span> <span class="kn">import</span> <span class="n">array</span>
<span class="n">CyclicIntArray</span> <span class="o">=</span> <span class="n">CyclicSequence</span><span class="p">(</span><span class="n">array</span><span class="p">,</span> <span class="k">lambda</span> <span class="n">seq</span><span class="p">:</span> <span class="n">array</span><span class="p">(</span><span class="s">&#39;i&#39;</span><span class="p">,</span> <span class="n">seq</span><span class="p">))</span>
<span class="n">CyclicUIntArray</span> <span class="o">=</span> <span class="n">CyclicSequence</span><span class="p">(</span><span class="n">array</span><span class="p">,</span> <span class="k">lambda</span> <span class="n">seq</span><span class="p">:</span> <span class="n">array</span><span class="p">(</span><span class="s">&#39;I&#39;</span><span class="p">,</span> <span class="n">seq</span><span class="p">))</span>
<span class="n">CyclicLongArray</span> <span class="o">=</span> <span class="n">CyclicSequence</span><span class="p">(</span><span class="n">array</span><span class="p">,</span> <span class="k">lambda</span> <span class="n">seq</span><span class="p">:</span> <span class="n">array</span><span class="p">(</span><span class="s">&#39;l&#39;</span><span class="p">,</span> <span class="n">seq</span><span class="p">))</span>
<span class="n">CyclicULongArray</span> <span class="o">=</span> <span class="n">CyclicSequence</span><span class="p">(</span><span class="n">array</span><span class="p">,</span> <span class="k">lambda</span> <span class="n">seq</span><span class="p">:</span> <span class="n">array</span><span class="p">(</span><span class="s">&#39;L&#39;</span><span class="p">,</span> <span class="n">seq</span><span class="p">))</span>
</pre></div>
</div>
</div>
<div class="section" id="module-fatghol.iterators">
<span id="fatghol-iterators"></span><h3><cite>fatghol.iterators</cite><a class="headerlink" href="#module-fatghol.iterators" title="Permalink to this headline">¶</a></h3>
<p>Iterator classes and utility functions.</p>
<dl class="class">
<dt id="fatghol.iterators.BufferingIterator">
<em class="property">class </em><tt class="descclassname">fatghol.iterators.</tt><tt class="descname">BufferingIterator</tt><big>(</big><em>initial=None</em><big>)</big><a class="reference internal" href="_modules/fatghol/iterators.html#BufferingIterator"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.iterators.BufferingIterator" title="Permalink to this definition">¶</a></dt>
<dd><p>Iterate over items stored in an internal buffer; when all items
in the buffer have been handed out to caller, refill the buffer by
calling <cite>self.refill()</cite> and start over again.</p>
<p>This is intended as a base class for iterators that can generate
more than one value per invocation; still, by the iterator
protocol, they should return only one value to caller.  Subclasses
of <cite>BufferingIterator</cite> should only need to define the <cite>refill()</cite>
method, returning a list (or other iterable) with items that
should be inserted in the buffer.</p>
<p>The base class implementation just returns the items passed in the
<cite>initial</cite> constructor argument and then raise <cite>StopIteration</cite>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">b</span> <span class="o">=</span> <span class="n">BufferingIterator</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">3</span><span class="p">])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">for</span> <span class="n">x</span> <span class="ow">in</span> <span class="n">b</span><span class="p">:</span> <span class="k">print</span> <span class="n">x</span>
<span class="go">1</span>
<span class="go">2</span>
<span class="go">3</span>

<span class="gp">&gt;&gt;&gt; </span><span class="nb">list</span><span class="p">(</span><span class="n">BufferingIterator</span><span class="p">())</span>
<span class="go">[]</span>
</pre></div>
</div>
<dl class="method">
<dt id="fatghol.iterators.BufferingIterator.next">
<tt class="descname">next</tt><big>(</big><big>)</big><a class="reference internal" href="_modules/fatghol/iterators.html#BufferingIterator.next"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.iterators.BufferingIterator.next" title="Permalink to this definition">¶</a></dt>
<dd><p>Return next item from queue, refilling queue if empty.</p>
</dd></dl>

<dl class="method">
<dt id="fatghol.iterators.BufferingIterator.refill">
<tt class="descname">refill</tt><big>(</big><big>)</big><a class="reference internal" href="_modules/fatghol/iterators.html#BufferingIterator.refill"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.iterators.BufferingIterator.refill" title="Permalink to this definition">¶</a></dt>
<dd><p>Return new items to store in the buffer.</p>
<p>At end of iteration, <cite>refill</cite> may either raise
<cite>StopIteration</cite>, or just return an empty list.</p>
<p>Sub-classes should override this method: the default
implementation just signals <cite>StopIteration</cite>.</p>
</dd></dl>

</dd></dl>

<dl class="class">
<dt id="fatghol.iterators.IndexedIterator">
<em class="property">class </em><tt class="descclassname">fatghol.iterators.</tt><tt class="descname">IndexedIterator</tt><big>(</big><em>lst</em>, <em>start=0</em><big>)</big><a class="reference internal" href="_modules/fatghol/iterators.html#IndexedIterator"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.iterators.IndexedIterator" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the items corresponding to indices <cite>start</cite>, <cite>start+1</cite>, etc.
in the initialization sequence <cite>lst</cite>.</p>
<p>Iteration stops as soon as an <cite>IndexError</cite> (indicating
out-of-bounds) is returned.</p>
<p>Examples:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">lst</span> <span class="o">=</span> <span class="p">[</span><span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">]</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">for</span> <span class="n">x</span> <span class="ow">in</span> <span class="n">IndexedIterator</span><span class="p">(</span><span class="n">lst</span><span class="p">):</span> <span class="k">print</span> <span class="n">x</span><span class="p">,</span>
<span class="go">0 1 2 3</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">for</span> <span class="n">y</span> <span class="ow">in</span> <span class="n">IndexedIterator</span><span class="p">(</span><span class="n">lst</span><span class="p">,</span> <span class="mi">2</span><span class="p">):</span> <span class="k">print</span> <span class="n">y</span><span class="p">,</span>
<span class="go">2 3</span>
</pre></div>
</div>
</dd></dl>

<dl class="class">
<dt id="fatghol.iterators.chunks">
<em class="property">class </em><tt class="descclassname">fatghol.iterators.</tt><tt class="descname">chunks</tt><big>(</big><em>sizes</em>, <em>iterable</em><big>)</big><a class="reference internal" href="_modules/fatghol/iterators.html#chunks"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.iterators.chunks" title="Permalink to this definition">¶</a></dt>
<dd><p>Lump items from iterable into chunks of specified size.</p>
<p>Instanciate the iterator passing a sequence of chunk sizes in
argument 1 and an iterable to consume in argument 2:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="k">for</span> <span class="n">c</span> <span class="ow">in</span> <span class="n">chunks</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">1</span><span class="p">],</span> <span class="nb">xrange</span><span class="p">(</span><span class="mi">3</span><span class="p">)):</span> <span class="k">print</span> <span class="n">c</span>
<span class="go">[0]</span>
<span class="go">[1]</span>
<span class="go">[2]</span>
</pre></div>
</div>
<p>The list of chunk sizes may be any kind of sequence, for instance
a tuple or even a (possibly infinite) iterable:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="nb">list</span><span class="p">(</span><span class="n">chunks</span><span class="p">((</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">3</span><span class="p">),</span> <span class="nb">range</span><span class="p">(</span><span class="mi">6</span><span class="p">)))</span>
<span class="go">[[0], [1, 2], [3, 4, 5]]</span>
</pre></div>
</div>
<p>The total size of the chunks may be less than the size of the
iterator: remaining items in the iterator are not consumed:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="k">for</span> <span class="n">c</span> <span class="ow">in</span> <span class="n">chunks</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">],</span> <span class="nb">range</span><span class="p">(</span><span class="mi">6</span><span class="p">)):</span> <span class="k">print</span> <span class="n">c</span>
<span class="go">[0]</span>
<span class="go">[1, 2]</span>
</pre></div>
</div>
<p>As a special case, if a chunk has size 0, then an empty list is
returned in its place and no item from iterable is consumed:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="k">for</span> <span class="n">c</span> <span class="ow">in</span> <span class="n">chunks</span><span class="p">([</span><span class="mi">2</span><span class="p">,</span><span class="mi">0</span><span class="p">,</span><span class="mi">2</span><span class="p">],</span> <span class="nb">range</span><span class="p">(</span><span class="mi">4</span><span class="p">)):</span> <span class="k">print</span> <span class="n">c</span>
<span class="go">[0, 1]</span>
<span class="go">[]</span>
<span class="go">[2, 3]</span>
</pre></div>
</div>
<dl class="method">
<dt id="fatghol.iterators.chunks.next">
<tt class="descname">next</tt><big>(</big><big>)</big><a class="reference internal" href="_modules/fatghol/iterators.html#chunks.next"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.iterators.chunks.next" title="Permalink to this definition">¶</a></dt>
<dd><p>Return next chunk.</p>
</dd></dl>

</dd></dl>

</div>
<div class="section" id="module-fatghol.loadsave">
<span id="fatghol-loadsave"></span><h3><cite>fatghol.loadsave</cite><a class="headerlink" href="#module-fatghol.loadsave" title="Permalink to this headline">¶</a></h3>
<p>Poor man&#8217;s substitute for &#8220;pickle&#8221;, supporting Cython classes.</p>
</div>
<div class="section" id="module-fatghol.output">
<span id="fatghol-output"></span><h3><cite>fatghol.output</cite><a class="headerlink" href="#module-fatghol.output" title="Permalink to this headline">¶</a></h3>
<p>Classes and routines for writing Fatgraphs to files.</p>
</div>
<div class="section" id="module-fatghol.runtime">
<span id="fatghol-runtime"></span><h3><cite>fatghol.runtime</cite><a class="headerlink" href="#module-fatghol.runtime" title="Permalink to this headline">¶</a></h3>
<p>Global shared runtime state.</p>
<p>Implemented using the <cite>Singleton</cite> and <cite>Monostate</cite> patterns, see
<a class="reference external" href="http://code.activestate.com/recipes/66531/">http://code.activestate.com/recipes/66531/</a> for original code and a
useful discussion.</p>
</div>
<div class="section" id="module-fatghol.timing">
<span id="fatghol-timing"></span><h3><cite>fatghol.timing</cite><a class="headerlink" href="#module-fatghol.timing" title="Permalink to this headline">¶</a></h3>
<p>Utilities for timing sections of code.</p>
<dl class="function">
<dt id="fatghol.timing.get">
<tt class="descclassname">fatghol.timing.</tt><tt class="descname">get</tt><big>(</big><em>label</em><big>)</big><a class="reference internal" href="_modules/fatghol/timing.html#get"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.timing.get" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the time elapsed between the <cite>start</cite> and <cite>stop</cite> calls to
the clock named <cite>label</cite>, as single floating-point number
expressing the duration in seconds.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name" colspan="2">Raises KeyError:</th></tr>
<tr><td>&nbsp;</td><td class="field-body">If <cite>label</cite> was never passed to <cite>timing.stop</cite>.</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="function">
<dt id="fatghol.timing.start">
<tt class="descclassname">fatghol.timing.</tt><tt class="descname">start</tt><big>(</big><em>label</em><big>)</big><a class="reference internal" href="_modules/fatghol/timing.html#start"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.timing.start" title="Permalink to this definition">¶</a></dt>
<dd><p>Start a clock.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><strong>label</strong> (<em>str</em>) &#8211; Arbitrary string identifying this clock for</td>
</tr>
</tbody>
</table>
<p>later reference.</p>
</dd></dl>

<dl class="function">
<dt id="fatghol.timing.stop">
<tt class="descclassname">fatghol.timing.</tt><tt class="descname">stop</tt><big>(</big><em>label</em><big>)</big><a class="reference internal" href="_modules/fatghol/timing.html#stop"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.timing.stop" title="Permalink to this definition">¶</a></dt>
<dd><p>Stop a clock, given its reference label.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><strong>label</strong> (<em>str</em>) &#8211; Arbitrary string identifying this clock;</td>
</tr>
</tbody>
</table>
<p>must match one of the arguments given to <cite>timing.start</cite>.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name" colspan="2">Raises KeyError:</th></tr>
<tr><td>&nbsp;</td><td class="field-body">If <cite>label</cite> was never passed to <cite>timing.start</cite>.</td>
</tr>
</tbody>
</table>
</dd></dl>

</div>
<div class="section" id="module-fatghol.utils">
<span id="fatghol-utils"></span><h3><cite>fatghol.utils</cite><a class="headerlink" href="#module-fatghol.utils" title="Permalink to this headline">¶</a></h3>
<p>A collection of small utility functions.</p>
<p>These were mostly ripped out of <cite>rg.py</cite> for readability.</p>
<dl class="function">
<dt id="fatghol.utils.concat">
<tt class="descclassname">fatghol.utils.</tt><tt class="descname">concat</tt><big>(</big><em>seqs</em><big>)</big><a class="reference internal" href="_modules/fatghol/utils.html#concat"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.utils.concat" title="Permalink to this definition">¶</a></dt>
<dd><p>Return concatenation of all sequences in <cite>seqs</cite>.</p>
<p>Examples:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">concat</span><span class="p">([[</span><span class="mi">0</span><span class="p">]])</span>
<span class="go">[0]</span>

<span class="gp">&gt;&gt;&gt; </span><span class="n">concat</span><span class="p">([[</span><span class="mi">0</span><span class="p">],[</span><span class="mi">1</span><span class="p">]])</span>
<span class="go">[0, 1]</span>

<span class="gp">&gt;&gt;&gt; </span><span class="n">concat</span><span class="p">([</span><span class="s">&#39;ab&#39;</span><span class="p">,</span><span class="s">&#39;c&#39;</span><span class="p">])</span>
<span class="go">&#39;abc&#39;</span>
</pre></div>
</div>
</dd></dl>

<dl class="class">
<dt id="fatghol.utils.itranslate">
<em class="property">class </em><tt class="descclassname">fatghol.utils.</tt><tt class="descname">itranslate</tt><big>(</big><em>subst</em>, <em>iterable</em><big>)</big><a class="reference internal" href="_modules/fatghol/utils.html#itranslate"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.utils.itranslate" title="Permalink to this definition">¶</a></dt>
<dd><p>Return items from a sequence, substituting them as specified.</p>
<p>First argument <cite>subst</cite> is a dictionary, specifying substitutions
to be applied.  If an item matches a key of the <cite>subst</cite>
dictionary, the associated dictionary value is returned instead;
unless the value is <cite>None</cite>, in which case the item is skipped
altogether.</p>
<dl class="docutils">
<dt><em>Note:</em> you should use an appropriate <cite>dict</cite>-subclass if you want</dt>
<dd>to translate items which are not immutable.</dd>
<dt>Examples::</dt>
<dd><div class="first last highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="nb">list</span><span class="p">(</span><span class="n">itranslate</span><span class="p">({</span><span class="mi">0</span><span class="p">:</span><span class="bp">None</span><span class="p">,</span> <span class="mi">3</span><span class="p">:</span><span class="mi">2</span><span class="p">},</span> <span class="p">[</span><span class="mi">2</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">0</span><span class="p">,</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">3</span><span class="p">]))</span>
<span class="go">[2, 1, 1, 2]</span>
</pre></div>
</div>
</dd>
</dl>
</dd></dl>

<dl class="function">
<dt id="fatghol.utils.lconcat">
<tt class="descclassname">fatghol.utils.</tt><tt class="descname">lconcat</tt><big>(</big><em>seqs</em><big>)</big><a class="reference internal" href="_modules/fatghol/utils.html#lconcat"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.utils.lconcat" title="Permalink to this definition">¶</a></dt>
<dd><p>Return list concatenation of all sequences in <cite>seqs</cite>.</p>
<p>Examples:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">lconcat</span><span class="p">([[</span><span class="mi">0</span><span class="p">]])</span>
<span class="go">[0]</span>

<span class="gp">&gt;&gt;&gt; </span><span class="n">lconcat</span><span class="p">([[</span><span class="mi">0</span><span class="p">],[</span><span class="mi">1</span><span class="p">]])</span>
<span class="go">[0, 1]</span>

<span class="gp">&gt;&gt;&gt; </span><span class="n">lconcat</span><span class="p">([</span><span class="s">&#39;ab&#39;</span><span class="p">,</span><span class="s">&#39;c&#39;</span><span class="p">])</span>
<span class="go">[&#39;a&#39;, &#39;b&#39;, &#39;c&#39;]</span>
</pre></div>
</div>
</dd></dl>

<dl class="function">
<dt id="fatghol.utils.ltranslate">
<tt class="descclassname">fatghol.utils.</tt><tt class="descname">ltranslate</tt><big>(</big><em>subst</em>, <em>iterable</em><big>)</big><a class="reference internal" href="_modules/fatghol/utils.html#ltranslate"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.utils.ltranslate" title="Permalink to this definition">¶</a></dt>
<dd><p>Return list of items from a sequence, substituting them as specified.</p>
<p>First argument <cite>subst</cite> is a dictionary, specifying substitutions
to be applied.  If an item matches a key of the <cite>subst</cite>
dictionary, the associated dictionary value is returned instead;
unless the value is <cite>None</cite>, in which case the item is skipped
altogether.</p>
<dl class="docutils">
<dt><em>Note:</em> you should use an appropriate <cite>dict</cite>-subclass if you want</dt>
<dd>to translate items which are not immutable.</dd>
<dt>Examples::</dt>
<dd><div class="first last highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">ltranslate</span><span class="p">({</span><span class="mi">0</span><span class="p">:</span><span class="bp">None</span><span class="p">,</span> <span class="mi">3</span><span class="p">:</span><span class="mi">2</span><span class="p">},</span> <span class="p">[</span><span class="mi">2</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">0</span><span class="p">,</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">3</span><span class="p">])</span>
<span class="go">[2, 1, 1, 2]</span>
</pre></div>
</div>
</dd>
</dl>
</dd></dl>

<dl class="function">
<dt id="fatghol.utils.positive_int">
<tt class="descclassname">fatghol.utils.</tt><tt class="descname">positive_int</tt><big>(</big><em>arg</em><big>)</big><a class="reference internal" href="_modules/fatghol/utils.html#positive_int"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.utils.positive_int" title="Permalink to this definition">¶</a></dt>
<dd><p>Convert a string or number to a positive integer, if possible.
Behaves just like the built-in <cite>int</cite> (which see), and additionally
raises <cite>ValueError</cite> if the converted integer is less-then or equal
to 0.</p>
</dd></dl>

<dl class="function">
<dt id="fatghol.utils.rotated">
<tt class="descclassname">fatghol.utils.</tt><tt class="descname">rotated</tt><big>(</big><em>L</em>, <em>p</em><big>)</big><a class="reference internal" href="_modules/fatghol/utils.html#rotated"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.utils.rotated" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a copy of the given list <cite>L</cite>, with items rotated <cite>p</cite>
positions leftwards.</p>
<p>Examples:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">rotated</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">3</span><span class="p">,</span><span class="mi">4</span><span class="p">,</span><span class="mi">5</span><span class="p">],</span> <span class="mi">2</span><span class="p">)</span>
<span class="go">[3, 4, 5, 1, 2]</span>
</pre></div>
</div>
</dd></dl>

<dl class="function">
<dt id="fatghol.utils.sign">
<tt class="descclassname">fatghol.utils.</tt><tt class="descname">sign</tt><big>(</big><em>x</em><big>)</big><a class="reference internal" href="_modules/fatghol/utils.html#sign"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#fatghol.utils.sign" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the sign of <cite>x</cite>: that is, 0 if <cite>x</cite> is zero, +1 iff it is
positive, -1 iff it is negative.</p>
<p>Examples:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">sign</span><span class="p">(</span><span class="mi">0</span><span class="p">)</span>
<span class="go">0</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">sign</span><span class="p">(</span><span class="mi">3</span><span class="p">)</span>
<span class="go">1</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">sign</span><span class="p">(</span><span class="o">-</span><span class="mi">5</span><span class="p">)</span>
<span class="go">-1</span>
</pre></div>
</div>
</dd></dl>

</div>
</div>
</div>


          </div>
        </div>
      </div>
      <div class="sphinxsidebar">
        <div class="sphinxsidebarwrapper">
  <h3><a href="index.html">Table Of Contents</a></h3>
  <ul>
<li><a class="reference internal" href="#">FatGHoL programming API</a><ul>
<li><a class="reference internal" href="#fatgraph-related-modules">Fatgraph-related modules</a><ul>
<li><a class="reference internal" href="#module-fatghol.rg"><cite>fatghol.rg</cite></a></li>
<li><a class="reference internal" href="#module-fatghol.homology"><cite>fatghol.homology</cite></a></li>
<li><a class="reference internal" href="#module-fatghol.graph_homology"><cite>fatghol.graph_homology</cite></a></li>
<li><a class="reference internal" href="#module-fatghol.valences"><cite>fatghol.valences</cite></a></li>
</ul>
</li>
<li><a class="reference internal" href="#utility-modules">Utility modules</a><ul>
<li><a class="reference internal" href="#module-fatghol.aggregate"><cite>fatghol.aggregate</cite></a></li>
<li><a class="reference internal" href="#module-fatghol.cache"><cite>fatghol.cache</cite></a></li>
<li><a class="reference internal" href="#module-fatghol.combinatorics"><cite>fatghol.combinatorics</cite></a></li>
<li><a class="reference internal" href="#module-fatghol.const"><cite>fatghol.const</cite></a></li>
<li><a class="reference internal" href="#module-fatghol.cyclicseq"><cite>fatghol.cyclicseq</cite></a></li>
<li><a class="reference internal" href="#module-fatghol.iterators"><cite>fatghol.iterators</cite></a></li>
<li><a class="reference internal" href="#module-fatghol.loadsave"><cite>fatghol.loadsave</cite></a></li>
<li><a class="reference internal" href="#module-fatghol.output"><cite>fatghol.output</cite></a></li>
<li><a class="reference internal" href="#module-fatghol.runtime"><cite>fatghol.runtime</cite></a></li>
<li><a class="reference internal" href="#module-fatghol.timing"><cite>fatghol.timing</cite></a></li>
<li><a class="reference internal" href="#module-fatghol.utils"><cite>fatghol.utils</cite></a></li>
</ul>
</li>
</ul>
</li>
</ul>

  <h4>Previous topic</h4>
  <p class="topless"><a href="using.html"
                        title="previous chapter">Using FatGHoL</a></p>
  <h3>This Page</h3>
  <ul class="this-page-menu">
    <li><a href="_sources/api.txt"
           rel="nofollow">Show Source</a></li>
  </ul>
<div id="searchbox" style="display: none">
  <h3>Quick search</h3>
    <form class="search" action="search.html" method="get">
      <input type="text" name="q" size="18" />
      <input type="submit" value="Go" />
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
    <p class="searchtip" style="font-size: 90%">
    Enter search terms or a module, class or function name.
    </p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             >index</a></li>
        <li class="right" >
          <a href="py-modindex.html" title="Python Module Index"
             >modules</a> |</li>
        <li class="right" >
          <a href="using.html" title="Using FatGHoL"
             >previous</a> |</li>
        <li><a href="index.html">FatGHoL v5.4 documentation</a> &raquo;</li> 
      </ul>
    </div>

    <div class="footer">
        &copy; Copyright 2012, Riccardo Murri.
      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.7.
    </div>
<div class="footer">This page uses <a href="http://analytics.google.com/">
Google Analytics</a> to collect statistics. You can disable it by blocking
the JavaScript coming from www.google-analytics.com.
<script type="text/javascript">
  (function() {
    var ga = document.createElement('script');
    ga.src = ('https:' == document.location.protocol ?
              'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
    ga.setAttribute('async', 'true');
    document.documentElement.firstChild.appendChild(ga);
  })();
</script>
</div>

  </body>
</html>